Migrating B2C projects to version 2 of the Frontend SDK

Migrate your project

To migrate your B2C project to version 2 of the Frontend SDK, follow these steps:

1. Update the @commercetools/frontend-sdk package to the latest SDK version in one of the following ways:

   • Run the Yarn command: yarn upgrade @commercetools/frontend-sdk.
   • Go to your project's package.json file and update the version number to the latest version listed on NPM. Save the file, then run yarn install and yarn.lock.

2. Go to your project's events file at packages/PROJECT_NAME/frontend/sdk/composable-commerce/types/events/ComposableCommerceEvents.ts. Add the following events to the file:

productFetched: { product: unknown };
productsQueried: { query: unknown; result: unknown };
productCategoriesQueried: { query: unknown; result: unknown };
searchableProductAttributesFetched: { filterFields: unknown[] };
projectSettingsFetched: { projectSettings: unknown };
productAddedToCart: { product: unknown; quantity: number };
productRemovedFromCart: { product: unknown; quantity: number };
productUpdatedInCart: { product: unknown; newQuantity: number };
cartFetched: { cart: unknown };
cartUpdated: {
  account?: {
    email: string;
  };
  shipping?: unknown;
  billing?: unknown;
};
shippingMethodsFetched: { shippingMethods: unknown[] };
availableShippingMethodsFetched: { shippingMethods: unknown[] };
shippingMethodUpdated: { shippingMethod: unknown };
discountCodeRedeemed: { discountCode: string; cart?: unknown };
discountCodeRemoved: { discountCode: string; cart?: unknown };
cartCheckedOut: {};
accountFetched: { account: unknown };
userLoggedIn: { account: unknown };
userLoggedOut: {};
userRegistered: { account: unknown };
accountConfirmed?: { account: unknown };
accountConfirmationEmailRequested?: { email: string };
passwordChanged: {};
passwordResetRequested: {};
passwordReset: {};
accountUpdated: { account: unknown };
accountAddressAdded: { address: unknown };
accountAddressUpdated: { address: unknown };
accountAddressRemoved: { addressId: string };
defaultBillingAddressSet: { address: unknown };
defaultShippingAddressSet: { address: unknown };
wishlistFetched: { wishlist: unknown };
lineItemAddedToWishlist: { lineItem: unknown };
lineItemRemovedFromWishlist: { lineItemId: string };
wishlistLineItemUpdated: { lineItem: unknown };

3. In all packages/PROJECT_NAME/frontend/sdk/composable-commerce/library/actions/* files, replace skipQueue with parallel in the options parameters of the SDK.callAction arguments. By default, all actions are executed asynchronously in version 2 of the SDK. To override this and queue actions for sequential execution, pass parallel: false to the SDK.callAction argument.

   In packages/PROJECT_NAME/frontend/frontastic/hooks/useProduct/index.ts, in the useProduct hook, remove the skipQueue parameter. Some older projects may not have this parameter.

4. In packages/PROJECT_NAME/frontend/sdk/composable-commerce/library/actions/AccountActions, replace the rememberMeCookieAsync import with rememberMeCookie, and update all references to it.

   By default, all cookie management methods are asynchronous.

5. In packages/PROJECT_NAME/frontend/sdk/composable-commerce/types/payloads/AccountPayloads.ts, change the UpdateAccountAddressPayload type to { address: Address }. Then, update the following references:

   • In packages/PROJECT_NAME/frontend/sdk/composable-commerce/library/payloads/AccountPayloads.ts, replace the updateAddress action to payload.address.
   • In packages/PROJECT_NAME/frontend/frontastic/hooks/useAccount/index.ts, update the updateAddress hook to pass the { address } object.
   • In packages/PROJECT_NAME/backend/commerce-commercetools/actionControllers/AccountController.ts, in the updateAddress action, change the response body deserialisation type to { address: Address } and update further references if needed.
   In version 2 of the Frontend SDK, you can no longer pass objects with payload types of unknown. You can pass only AcceptedPayloadTypes objects.

6. If your project contains an extension for Adyen, complete this step. Otherwise, skip to step 7.

   In packages/PROJECT_NAME/frontend/frontastic/hooks/useAdyen/index.ts, in the makePayment method, wrap the payload argument in an object. Then, change the response body deserialisation type to reflect the change and update further references if needed.

7. In packages/PROJECT_NAME/frontend/types/index.d.ts, delete the following declarations:

   Declarations to delete from the type index fileTypeScript React

   interface Page extends BasePage {
     sections: Record<string, Section>;
   }
   declare module '@commercetools/frontend-sdk/lib/types/api/page/PageResponse' {
     interface PageResponse {
       page: Page;
       pageFolder: PageFolder;
       data: PageViewData;
     }
   }

8. In packages/PROJECT_NAME/frontend/frontastic/renderer/index.tsx, add a non-null assertion operator to section errors. For example, update section. to section!. in the sections mapping in the component return. This is to ensure compatibility and correct syntax for TypeScript.

9. In packages/PROJECT_NAME/frontend/app/[locale]/[[...slug]]/page.tsx, replace all of the file's content with the content in the latest version of the page.tsx file.

10. If you have made custom updates to your project, check them against this guide and the list of changes and update any references or dependencies as needed.