@makaira/storefront-react

This package is a wrapper to bring a reactive shop adapter to your react storefront. This react wrapper is SSR compatible. It is completely build by the usage of react hooks.

The package will automatically handle loading data like the user, the cart or the wishlist. Also it handles modifications in the state change by listening to the events emitted by the shop adapter client.

This package gives you using hooks access to the loaded data and holds some common data like the total amount of products in the cart.

Installation

yarn install @makaira/storefront-react

or

npm i @makaira/storefront-react

Adding to your project

For simplicity we are here using the local shop adapter to demonstrate how to add the react wrapper to your storefront.

import { StorefrontShopAdapterLocal } from '@makaira/storefront-shop-adapter-local'
import { ShopProvider } from '@makaira/storefront-react'

const client = new StorefrontShopAdapterLocal()

function Index() {
  return (
    <ShopProvider client={shopClient}>
      <App />
    </ShopProvider>
  )
}

In addition if you are using typescript in your project and want to get the correct autosuggestion you have to create a new declaration file (e.g index.d.ts) with the following content:

import '@makaira/storefront-react'
import { StorefrontShopAdapterLocal } from '@makaira/storefront-shop-adapter-local'

declare module '@makaira/storefront-react' {
  interface StorefrontReactCustomClient {
    client: StorefrontShopAdapterLocal
  }
}

Props for the ShopProvider

| Property | Required/Optional | Description | Type | | ---------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | client | required | The shop adapter client. | StorefrontReactCustomClient['client'] | | bootstrap | optional | By default the react wrapper loads the the main data that is required for most storefronts. These can be disabled or customized. | object | | - cart | optional | By default the current cart will be loaded by calling client.cart.getCart({input:{}}). If you set this value to false loading is disabled. If your turn it back to true it will automatically loads the cart. If you want to customize the data that is loaded you can also pass a function that returns a Promise<MakairaResponse>. The dataproperty will then be written into the state. | boolean \| (() => Promise<MakairaResponse<StorefrontReactCustomTypes['cart'], any, Error> >) | | - user | optional | By default the current user will be loaded by calling client.user.getUser({input:{}}). If you set this value to false loading is disabled. If your turn it back to true it will automatically loads the user. If you want to customize the data that is loaded you can also pass a function that returns a Promise<MakairaResponse>. The dataproperty will then be written into the state. | boolean \| (() => Promise<MakairaResponse<StorefrontReactCustomTypes['user'], any, Error> >) | | - wishlist | optional | By default the current wishlist will be loaded by calling client.wishlist.getWishlist({input:{}}). If you set this value to false loading is disabled. If your turn it back to true it will automatically loads the wishlist. If you want to customize the data that is loaded you can also pass a function that returns a Promise<MakairaResponse>. The dataproperty will then be written into the state. | boolean \| (() => Promise<MakairaResponse<StorefrontReactCustomTypes['wishlist'], any, Error> >) |

Usage with typescript

In the above section we already explained how to set the correct shop adapter. In addition to these you can also adjust the typescript definition of the in the state stored data.

By default you don't need to do so. But if you set a custom bootstrap loader this might by helpful.

To do so add to your declaration file the following content:

import '@makaira/storefront-react'
import { StorefrontShopAdapterLocal } from '@makaira/storefront-shop-adapter-local'

declare module '@makaira/storefront-react' {
  // only overwrite one specific data
  interface StorefrontReactCustomTypes {
    cart: { id: string }
  }

  // update overwrite specific data
  interface StorefrontReactCustomTypes {
    cart: { id: string }
    user: { id: string }
  }

  // or overwrite them all
  interface StorefrontReactCustomTypes {
    cart: { id: string }
    user: { id: string }
    wishlist: { id: string }
  }
}

Available Hooks

useShopClient

This hook can be used to access the shop adapter client passed to the ShopProvider.

function App() {
  const { client } = useShopClient()

  return <></>
}

Arguments

No Arguments to pass

Returned properties

| Property | Description | Type | | -------- | ---------------------------------------- | --------------------------------------- | | client | The client passed to the ShopProvider. | StorefrontReactCustomClient['client'] |

useShopCart

This hook can be used to access the current cart.

function App() {
  const { cart } = useShopCart()

  return <></>
}

Arguments

No Arguments to pass

Returned properties

| Property | Description | Type | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | | cart | The current cart. | null \| undefined \| StorefrontReactCustomTypes['user'] | | productsInCart | The current amount of products in the cart. It counts the number of unique products but not their quantity in the cart. When in the cart product A and product B with each have a quantity set to 3 is, productsInCart will 2. | number | | quantityInCart | The current total amount of products with their quantity. When in the cart product A and product B with each have a quantity set to 3 is, quantityInCart will 6. | number | | totalPriceInCart | The current total price of all products in the cart including their quantities. | number |

useShopUser

This hook can be used to access the current user.

function App() {
  const { user } = useShopUser()

  return <></>
}

Arguments

No Arguments to pass

Returned properties

| Property | Description | Type | | -------- | ----------------- | ----- | --------- | ----------------------------------- | | user | The current user. | null | undefined | StorefrontReactCustomTypes['user'] |

useShopWishlist

This hook can be used to access the current wishlist.

function App() {
  const { wishlist } = useShopWishlist()

  return <></>
}

Arguments

No Arguments to pass

Returned properties

| Property | Description | Type | | ------------------- | ---------------------------------------------------- | ------------------------------------------------------------ | | wishlist | The current wishlist. | null \| undefined \| StorefrontReactCustomTypes['cart'] | | isProductInWishlist | A function to check if a product is in the wishlist. | (id: string) => MakairaResponse<boolean, undefined, Error> |

useShopReviews

This hook can be used to reviews for a specific product

function App() {
  const { loading, error, data, raw } = useShopWishlist({
    product: { id: 'foo' },
  })

  return <></>
}

Arguments

| Property | Required/Optional | Description | Type | | ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------- | --------- | | product | required | The product to get the reviews from. | object | | - id | required | The id of the product to get reviews from. | string | | pagination | optional | To allow pagination you can here set the pagination information | object | | - offset | optional | The pagination offset. | number | | - limit | optional | The pagination limit. | number | | refetchOnReviewCreated | optional | Indicator if the review list should be refetched if the ReviewCreateEvent was emitted. Default is false. | boolean |

Returned properties

| Property | Description | Type | | -------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | loading | Indicator if the reviews are currently fetching or if the next pagination is loading. | boolean | | error | Indicator if an error occurred while loading the reviews. | Error \| undefined | | data | The data property returned by the client.reviews.getReviews() containing the reviews. | Unified data response of client.reviews.getReviews() | | raw | The raw property returned by the client.reviews.getReviews(). | Shop adapter specific raw response of client.reviews.getReviews() | | refetch | Function to force a reload with the current product and pagination information | () => void |