Documentation

Migrating B2C projects to version 2 of the Frontend SDK

Elevate, May 20-22-2025, Miami Beach, Florida

This guide helps you migrate your out-of-the-box B2C projects from version 1 to version 2 of the commercetools Frontend SDK. If you made custom changes to your project, you must also check if these need updates against the breaking changes.

For migrating B2B projects, see the migration guide for B2B projects.

Version 2 of the SDK contains breaking changes.

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:

  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 exported ComposableCommerceEvents type in the file:

    Events to add to the ComposableCommerceEvents.ts filetsx
    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 };

    In version 1 of the SDK, this event was defined in the @commercetools/frontend-sdk npm package, in the StandardEvents.ts file.

  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/actions/AccountActions.ts, within the updateAddress function, replace the payload passed in the addressesAreEqual function 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 filetsx
    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.