diff --git a/packages/commerce-sdk-react/README.md b/packages/commerce-sdk-react/README.md index 660d05e7b6..916a6b970b 100644 --- a/packages/commerce-sdk-react/README.md +++ b/packages/commerce-sdk-react/README.md @@ -1,24 +1,45 @@ # Commerce SDK React -A library of React hooks for fetching data from Salesforce B2C Commerce. +

+A collection of react-query hooks for fetching, caching, and mutating data from the Salesforce B2C Commerce API (SCAPI).

-## Documentation +## 🎯 Features -The full documentation for PWA Kit and Managed Runtime is hosted on the [Salesforce Developers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/overview) portal. +- Shopper authentication & token management via [SLAS](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-login) +- Server side data fetching (in conjuction with PWA Kit) +- Phased Launch support ([plugin_slas](https://github.com/SalesforceCommerceCloud/plugin_slas) compatible) +- Built-in caching for easy state management + - automatic cache invalidations/updates via the library's built-in mutations + - automatic cache key generation +## ⚙️ Installation -## PWA-Kit Integration +```bash +npm install @salesforce/commerce-sdk-react @tanstack/react-query +``` -> To integration this library with your PWA-Kit application you can use the `CommerceApiProvider` directly given that you use the `withReactQuery` higher order component to wrap your `AppConfig` component. Below is a snippet of how this is accomplished. +## ⚡️ Quickstart (PWA Kit v2.3.0+) -``` +To integrate this library with your PWA Kit application you can use the `CommerceApiProvider` directly assuming that you use the `withReactQuery` higher order component to wrap your `AppConfig` component. Below is a snippet of how this is accomplished. + +```jsx // app/components/_app-config/index.jsx +import {CommerceApiProvider} from '@salesforce/commerce-sdk-react' import {withReactQuery} from 'pwa-kit-react-sdk/ssr/universal/components/with-react-query' const AppConfig = ({children}) => { return ( - + {children} ) @@ -42,20 +63,30 @@ const options = { export default withReactQuery(AppConfig, options) ``` -## Generic Integration +## ⚡️ Quickstart (Generic React App) -> You can use this library in any React application provided you bring your own QueryClient and QueryClientProvider. Below is a sample integration: +You can use this library in any React application by creating a new QueryClient and wrap your application with `QueryClientProvider`. For example: -``` -import {QueryClient, QueryClientConfig, QueryClientProvider} from '@tanstack/react-query' +```jsx +import {CommerceApiProvider} from '@salesforce/commerce-sdk-react' +import {QueryClient, QueryClientProvider} from '@tanstack/react-query' const App = ({children}) => { - const queryClient = new QueryClient(queryClientConfig) + const queryClient = new QueryClient() return ( - + {children} @@ -64,7 +95,224 @@ const App = ({children}) => { export default App ``` -### Useful Links: + +## Shopper Authentication and Token Management + +_💡 This section assumes you have read and completed the [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) guide._ + +To help reduce boilerplate code for managing shopper authentication, by default, this library automatically initializes shopper session and manages the tokens for developers. Currently, the library supports the [Public Client login flow](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html). + +### Shopper Session Initialization + +On `CommerceApiProvider` mount, the provider initializes shopper session by initiating the SLAS __Public Client__ login flow. The tokens are stored/managed/refreshed by the library. + +### Authenticate request queue + +While the library is fetching/refreshing the access token, the network requests will queue up until there is a valid access token. + +### Login helpers + +To leverage the managed shopper authentication feature, use the `useAuthHelper` hook for shopper login. + +Example: + +```jsx +import {AuthHelpers, useAuthHelper} from '@salesforce/commerce-sdk-react' + +const Example = () => { + const register = useAuthHelper(AuthHelpers.Register) + const login = useAuthHelper(AuthHelpers.LoginRegisteredUserB2C) + const logout = useAuthHelper(AuthHelpers.LogOut) + + return