React SDK Migration Guide
Chord’s Next.js starter used to include React hooks like useCart and useAnalytics in the src/hooks/actions directory. The release of Chord’s new React, react-autonomy, allows these hooks to be imported from the react-autonomy package instead. The Next.js starter has been updated to use this new SDK. If you developed a website based on a previous version of the Next.js starter, you may want to update your website code to use react-autonomy.
Going forward, all SDK features and fixes will be made to react-autonomy. react-autonomy also comes with some great new features!
react-autonomy has complete Typescript support with type definitions.
Removed dependency on CMS product catalog
Previously, all products in the CMS had to belong to a single catalog. A bootstrapReduxStore query fetched the catalog from the CMS on every page, and Redux stored the catalog and used it to add product metadata, like descriptions and images, to product-related Segment tracking events. react-autonomy removes this dependency on a product catalog and instead adds an optional product argument to some SDK methods, allowing you to provide the product from the CMS and control the CMS query.
react-autonomy includes function documentation following the JSDoc specification.
Improved hooks and methods
Names, parameters, and behavior has been standardized across the SDK.
Upgrading a Next.js site to use react-autonomy requires making the following broad changes. You can reference the starter diff to see the complete list of changes when we migrated the starter.
Remove these packages (they’re now dependencies of react-autonomy):
Add these packages:
Delete the bootstrapReduxStore query, because it’s no longer used.
Delete any queries referencing bootstrapReduxStore. For example, the article query at packages/nextjs-starter-autonomy/graphql-cms/queries/article.js used to export both a getArticle function and a getArticleWithReduxState function. The getArticleWithReduxState function should be deleted.
Delete references to get*WithReduxState queries in page templates. References to reduxWrapper should be replaced with a new utility, nextContentWrapper, that we’ve included in the Next.js starter to facilitate fetching the same content on every page (for example, notification banner content).
Here’s an example of how we’ve converted nextjs-starter-autonomy/pages/articles/[slug].js:
Add the ChordProvider component, and wrap the application with it in _app.js.
Delete deprecated files
react-autonomy includes React hooks and state management, so a lot of files previously included in the Next.js starter can be deleted. Delete these directories:
- src/hooks/actions (except for src/hooks/actions/use-translate.js)
Update React components
Hooks should be imported from @chordcommerce/react-autonomy instead of ~/hooks/actions:
Hooks and method names have changed, so this will need to be updated throughout your code. Reference the documentation to see how they’ve changed. For example:
Add product serializer
As mentioned above, some methods now have a product argument you can include to add details about the product to the Segment tracking event. nextjs-starter-autonomy/src/utils/chord/serialize.js provides a couple of convenience methods that serialize the Chord CMS Content Models into the correct object shape. You can customize these functions as needed, or write your own.