Implement Hybrid Authentication for PWA Kit v2

Use this guide to upgrade your PWA Kit application to version 2.10.0 and implement Hybrid Auth. The PWA Kit 2.10.0 release introduces significant changes, such as compatibility with Hybrid Auth and integration with the @salesforce/commerce-sdk-react package. PWA Kit v2.10.0 only supports SLAS Public Clients. For additional details, check out the complete pwa-kit GitHub diff to get a better understanding of the code changes.

Before starting the upgrade process, ensure you have:

• Node.js version 18.x or 20.x (upgraded from 14.x/16.x support)
• NPM version 9.x or 10.x (upgraded from 6.x/7.x/8.x support)
• Enable hybrid auth on your Business Manager instance and enable cookies on Managed Runtime. For details, see Hybrid Authentication.

The most significant update is the introduction of the new Commerce SDK React authentication system.

1. Check your current Node.js and npm versions.

   If your Node.js version is below 18.x, upgrade it first. If your npm version is below 9.x, upgrade it first.

1. Open your package.json file and update the following sections.

   Update the "engines" section.

   Update the "devDependencies" section with these new dependencies and version bumps.

2. Save the package.json file.

3. Clean install the new dependencies.

1. Open your config/default.js file.

2. Find the line that contains ssrFunctionNodeVersion and update it.

3. Save the config/default.js file.

Update your authentication implementation with the new Commerce SDK React system.

1. Remove old authentication files.

2. Update the utils.js file.

   Remove these imports from the top of the file.

   Remove these functions from app/commerce-api/utils.js.

   Keep all other utility functions, including keysToCamel and createOcapiFetch, as they're still needed.

3. Update the useCustomer hook. Open your app/hooks/use-customer.js file and update the authentication methods.

1. Open your app/commerce-api/index.js file.

2. Update the imports at the top of the file.

3. Update the auth module instantiation.

   Replace with this new code:

4. Find the section where SDK clients are instantiated (around line 100-150) and replace the entire SDK instantiation logic. Remove this old code:

   Replace with this new code:

5. Find and remove these methods from the CommerceAPI class:

6. Update the constants file. Add a new constant in app/commerce-api/constants.js.

1. Open your app/commerce-api/contexts.js file.

2. Add these new imports at the top.

3. Add the QueryClient configuration after the imports.

4. Replace the existing CommerceAPIProvider with this new implementation.

5. Save the app/commerce-api/contexts.js file.

1. Open your app/components/_app-config/index.jsx file.

2. Find the CommerceAPIProvider component and update it.

   Replace this code:

   With this code:

3. Save the app/components/_app-config/index.jsx file.

1. Open your app/components/_app/index.jsx file.

2. Remove the login call.

1. Start the development server.

2. Run the build to check for errors.

With PWA Kit v2.10.0, you now have access to powerful query hooks from @salesforce/commerce-sdk-react that provide automatic caching, loading states, and error handling for both hybrid and non-hybrid PWA Kit v2.x storefronts. Here's how to use them in your pages.

Create a minimal order list component using the new query hooks.

Check out the key benefits of the new query hooks.

• Automatic caching—Data is cached and shared.
• Loading states—Built-in loading management.
• Error handling—Automatic error states.
• Optimized fetching—Only fetches when customer is available.
• Simplified code—Less manual state management.

• PWA Kit Overview
• Hybrid Implementation Guidance
• Commerce SDK React Documentation