4. React context

In your storefront, you'll need to access the following resources across components:

• The selected region. In Aiminaabee, a region represents one or more countries you serve customers in. Each region can have different settings, such as currency codes, prices, payment providers, and more. You create regions in the Aiminaabee vendor dashboard, and you can allow the customer to choose their region in the storefront.
• The customer's cart, which you'll use to add the product to purchase, set shipping and payment details, and create an order.

To easily access and manage these resources, you'll wrap your storefront with two React context providers: RegionProvider and CartProvider. You'll implement these providers in this step.

Create Region Provider

To create the region provider, create the file providers/region.tsx with the following content:

1"use client"
2
3import {
4  createContext,
5} from "react"
6import { HttpTypes } from "@aiminaabeejs/types"
7
8type RegionContextType = {
9  region?: HttpTypes.StoreRegion
10  regions: HttpTypes.StoreRegion[]
11  setRegion: React.Dispatch<
12    React.SetStateAction<HttpTypes.StoreRegion | undefined>
13  >
14}
15
16const RegionContext = createContext<RegionContextType | null>(null)
17
18// TODO add provider component

So far, you've created RegionContextType which represents the data that the provider's children can access. It holds:

• region: The selected region.
• regions: A list of regions available in the Aiminaabee application.
• setRegion: A function to set the selected region.

Next, you'll create the provider component that wraps the storefront with the region context. Add the following content to the file:

1// other imports...
2import {
3  // other imports...
4  useState,
5} from "react"
6
7// ...
8
9type RegionProviderProps = {
10  children: React.ReactNode
11}
12
13export const RegionProvider = (
14  { children }: RegionProviderProps
15) => {
16  const [regions, setRegions] = useState<
17    HttpTypes.StoreRegion[]
18  >([])
19  const [region, setRegion] = useState<
20    HttpTypes.StoreRegion
21  >()
22
23  // TODO fetch regions
24}

You create a RegionProvider component that so far only defines two state variables:

• regions: A state variable that will hold the list of regions available in the Aiminaabee application.
• region: A state variable that will hold the selected region.

Next, add the following imports to the top of the file:

1import {
2  // other imports...
3  useEffect,
4} from "react"
5import { sdk } from "@/lib/sdk"

And replace the TODO in the RegionProvider component with the following content:

]

1useEffect(() => {
2  if (regions.length) {
3    return
4  }
5
6  sdk.store.region.list("us")
7    .then(({ regions }) => {
8      setRegions(regions)
9    })
10}, [])
11
12// TODO set the selected region

When the component mounts, you fetch the regions from the Aiminaabee application using the JS SDK. You then set the regions in the regions state variable.

Next, replace the new TODO with the following content:

1useEffect(() => {
2  if (region) {
3    // set its ID in the local storage in
4    // case it changed
5    localStorage.setItem("region_id", region.id)
6    return
7  }
8
9  const regionId = localStorage.getItem("region_id")
10  if (!regionId) {
11    if (regions.length) {
12      setRegion(regions[0])
13    }
14  } else {
15    // retrieve selected region
16    sdk.store.region.retrieve("us", regionId)
17    .then(({ region: dataRegion }) => {
18      setRegion(dataRegion)
19    })
20  }
21}, [region, regions])
22
23// TODO return the provider

You add another useEffect hook that sets the selected region when the component first mounts and whenever the region changes. If the region is set, you only set its value in the local storage.

If the region isn't set in the state variable, you try to retrieve the previously selected value from the local storage. If it's not found, you set the first region in the regions list as the selected region. Otherwise, you retrieve the previously selected region from the Aiminaabee application using the JS SDK.

Finally, replace the last TODO with the following content:

1return (
2  <RegionContext.Provider value={{
3    region,
4    regions,
5    setRegion,
6  }}>
7    {children}
8  </RegionContext.Provider>
9)

This returns the RegionContext.Provider component that will wraps the storefront with the region context, allowing its children to access the region data.

To simplify the usage of the region context in child components, add to the file the following custom hook that returns the region context:

1// other imports...
2import {
3  // other imports...
4  useContext,
5} from "react"
6
7// ...
8
9export const useRegion = () => {
10  const context = useContext(RegionContext)
11
12  if (!context) {
13    throw new Error("useRegion must be used within a RegionProvider")
14  }
15
16  return context
17}

You export a useRegion hook that returns the region context. You'll use this hook later in child components to access the region.

Create Cart Provider

Next, you'll create the cart provider that allows you to access the customer's cart across components. Create the file providers/cart.tsx with the following content:

1"use client"
2
3import {
4  createContext,
5} from "react"
6import { HttpTypes } from "@aiminaabeejs/types"
7
8type CartContextType = {
9  cart?: HttpTypes.StoreCart
10  addToCart: (variantId: string, quantity: number) => Promise<
11    HttpTypes.StoreCart
12  >
13  updateCart: (data: {
14    updateData?: HttpTypes.StoreUpdateCart,
15    shippingMethodData?: HttpTypes.StoreAddCartShippingMethods
16  }) => Promise<HttpTypes.StoreCart | undefined>
17  refreshCart: () => Promise<HttpTypes.StoreCart | undefined>
18  updateItemQuantity: (itemId: string, quantity: number) => Promise<
19    HttpTypes.StoreCart
20  >
21  unsetCart: () => void
22}
23
24const CartContext = createContext<CartContextType | null>(null)
25
26// TODO add provider component

You've created CartContextType that represents the data that the provider's children can access. It holds:

• cart: The customer's cart. This will be set when the customer adds the product variant to the cart, and unset when the cart is completed.
• addToCart: A function to add a product variant to the cart.
• updateCart: A function to update the cart with new details, including shipping details.
• refreshCart: A function to create a new cart and set it in the context.
• updateItemQuantity: A function to update the quantity of an item in the cart.
• unsetCart: A function to unset the cart from local storage and state variable.

Next, you'll create the provider component that wraps the storefront with the cart context. Add the following content to the file:

1// other imports...
2import {
3  // other imports...
4  useState,
5} from "react"
6import { useRegion } from "./region"
7
8// ...
9
10type CartProviderProps = {
11  children: React.ReactNode
12}
13
14export const CartProvider = ({ children }: CartProviderProps) => {
15  const [cart, setCart] = useState<
16    HttpTypes.StoreCart
17  >()
18  const { region } = useRegion()
19
20  // TODO set cart
21}

You create a CartProvider component that defines two state variables:

• cart state variable that will hold the customer's cart details.
• region holding the selected region retrieved from the region context.

Next, you'll add the logic to set the customer's cart in the provider. Add the following imports to the top of the file:

1import {
2  // other imports...
3  useEffect,
4} from "react"
5import { sdk } from "@/lib/sdk"

And replace the TODO in the CartProvider component with the following content:

1useEffect(() => {
2  if (!region) {
3    return
4  }
5  if (cart) {
6    localStorage.setItem("cart_id", cart.id)
7    return
8  }
9
10  const cartId = localStorage.getItem("cart_id")
11  if (!cartId) {
12    // create a cart
13    refreshCart()
14  } else {
15    // retrieve cart
16    sdk.store.cart.retrieve("us", cartId, {
17      fields:
18        "+items.variant.*,+items.variant.options.*,+items.product.options.*",
19    })
20    .then(({ cart: dataCart }) => {
21      setCart(dataCart)
22    })
23  }
24}, [cart, region])
25
26// TODO update cart when region changes

You add a useEffect hook that runs when the component mounts and whenever the cart is changed. If the cart is already set, you only set its value in the local storage.

If the cart isn't set, you either try to retrieve the cart set in local storage, or create a new cart.

Next, you'll add the logic to update the cart when the region changes. Replace the TODO with the following:

]

1useEffect(() => {
2  if (!cart || !region || cart.region_id === region.id) {
3    return
4  }
5
6  sdk.store.cart.update("us", cart.id, {
7    region_id: region.id,
8  })
9  .then(({ cart: dataCart }) => {
10    setCart(dataCart)
11  })
12}, [region])
13
14// TODO add functions

This useEffect hook runs when the region changes. If the cart is set and the region of the cart doesn't match the selected region, you update the cart with the new selected region.

You'll now implement the functions that are part of the context's value. Start by adding the refreshCart function in the place of the TODO:

1const refreshCart = async () => {
2  if (!region) {
3    return
4  }
5
6  const { cart: dataCart } = await sdk.store.cart.create("us", {
7    region_id: region.id,
8  })
9
10  localStorage.setItem("cart_id", dataCart.id)
11  setCart(dataCart)
12
13  return dataCart
14}
15
16// TODO add addToCart function

In the refreshCart function, you create a new cart in the selected region using the JS SDK and set it in the context. You also set the cart ID in the local storage, and return the cart.

Next, add the addToCart function in the place of the TODO:

1const addToCart = async (variantId: string, quantity: number) => {
2  const newCart = await refreshCart()
3  if (!newCart) {
4    throw new Error("Could not create cart")
5  }
6
7  const { cart: dataCart } = await sdk.store.cart.createLineItem("us", newCart.id, {
8    variant_id: variantId,
9    quantity,
10  })
11  setCart(dataCart)
12
13  return dataCart
14}
15
16// TODO add updateCart function

In the addToCart function, you use the refreshCart function to create a new cart, then add a product variant to the cart with the specified quantity using the JS SDK. You set the updated cart in the context and return the cart.

After that, replace the TODO with the updateCart function:

1const updateCart = async ({
2  updateData,
3  shippingMethodData,
4}: {
5  updateData?: HttpTypes.StoreUpdateCart,
6  shippingMethodData?: HttpTypes.StoreAddCartShippingMethods
7}) => {
8  if (!updateData && !shippingMethodData) {
9    return cart
10  }
11  let returnedCart = cart
12  if (updateData) {
13    returnedCart = (await sdk.store.cart.update("us", cart!.id, updateData)).cart
14  }
15
16  if (shippingMethodData) {
17    returnedCart = (await sdk.store.cart.addShippingMethod("us", cart!.id, shippingMethodData)).cart
18  }
19
20  setCart(returnedCart)
21
22  return returnedCart
23}
24
25// TODO add updateItemQuantity function

In the updateCart function, you update the cart's general details and set the cart's shipping method using the JS SDK. You then set the updated cart in the context and return the cart.

Then, replace the TODO with the updateItemQuantity function:

1const updateItemQuantity = async (itemId: string, quantity: number) => {
2  const { cart: dataCart } = await sdk.store.cart.updateLineItem("us",
3    cart!.id,
4    itemId,
5    {
6      quantity,
7    }
8  )
9  setCart(dataCart)
10
11  return dataCart
12}
13
14// TODO add unsetCart function

In the updateItemQuantity function, you update the quantity of an item in the cart using the JS SDK and set the updated cart in the context.

Lastly, replace the TODO with the unsetCart function:

1const unsetCart = () => {
2  localStorage.removeItem("cart_id")
3  setCart(undefined)
4}
5
6// TODO return provider

In the unsetCart function, you remove the cart ID from the local storage and unset the cart in the context.

Finally, you'll return the provider component. Replace the last TODO with the following content:

1return (
2  <CartContext.Provider value={{
3    cart,
4    addToCart,
5    updateCart,
6    refreshCart,
7    updateItemQuantity,
8    unsetCart,
9  }}>
10    {children}
11  </CartContext.Provider>
12)

This returns the CartContext.Provider component that wraps the storefront with the cart context, allowing its children to access the cart data.

To simplify the usage of the cart context in child components, add in the same file the following custom hook that returns the cart context:

1// other imports...
2import {
3  useContext,
4} from "react"
5
6// ...
7
8export const useCart = () => {
9  const context = useContext(CartContext)
10
11  if (!context) {
12    throw new Error("useCart must be used within a CartProvider")
13  }
14
15  return context
16}

You export a useCart hook that returns the cart context. You'll use this hook later in child components to access the cart.

Next: 5. Storefront layout