Documentation
All Release Notes

Breaking changes - Introduced version 2.0.0 of the commercetools Frontend SDK

12 November 2024
Frontend
Frontend Development
New feature
SDK

Version 2.0.0 of the SDK contains breaking changes.

Version 2.0.0 of the commercetools Frontend SDK introduces new features and bug fixes. We recommend upgrading to Version 2.0.0 of the SDK to ensure you get the newest features, improvements, and fixes.

For a step-by-step guide about how to update your SDK version, see the following:

Breaking changes

  • Commerce related events were removed and moved to the Composable Commerce integration.
  • In the page API, the getPage method now returns a union type of PageResponse and RedirectResponse instead of only a PageResponse.
  • In the Page type, the sections property changed from a Section array to an object with optional footer, head, and main properties of a Section type.
  • In the Page type, the state changed from a string to "default" | "published" | "draft" | "scheduled".
  • All page API and event-related types changed to interfaces.
  • In the SDK.configure method, the extensionVersion argument is now required.
  • In the SDK.callAction method, the skipQueue parameter was replaced with an optional parallel argument, with a default of true.
  • All synchronous cookie handling functionality was removed. The rememberMeCookieAsync object was renamed to rememberMeCookie and this is now the default functionality.
  • The previously deprecated Extension class was removed, this should be replaced with Integration.
  • The posixLocale property was deprecated and removed.
  • Getters for the endpoint, locale, currency, and customHeaderValue properties on the SDK class changed to functions.
  • In the Event class, the isDefaultPrevented, isCancelled, and isPropagationStopped properties were removed.
  • In the SDK.callActon method, the payload argument of the SDK.callActon is no longer unknown. Instead, the argument must be of type AcceptedPayloadTypes.
  • On the FetchError class, the constructor argument now accepts an options argument with the required error property of type string | Error.
  • On the ActionError class, the actionName property was removed and the constructor now only accepts a single options argument with the required error property of type string | Error.
  • On the PageError class, the path property was removed, and the constructor now only takes a single options argument with the required error property of type string | Error.
  • In BaseEvents, the errorCaught event property of frontasticRequestId?: string was added to a tracing object.

New features

  • The BaseEvents file replaces the StandardEvents one and adds the following events:

    • actionCalled: triggered when an action is called.
    • pageApiMethodCalled: triggered when a page API method is called.
    • fetchCalled: triggered when an action or a page API method is called.
    • actionFetchSuccessful: triggered when an action returns successfully.
    • pageApiFetchSuccessful: triggered when a page API method returns successfully.
    • fetchSuccessful: triggered when an action or a page API method returns successfully.
    • actionErrorCaught: triggered when an action error occurs.
    • pageApiErrorCaught: triggered a page API method error occurs.

  • To prevent accidental storage or logging, the SDK now redacts sensitive JSON and URL data for internal events. You can override this by passing one of the following to the new redactionHandlingOverride property in the SDK.configure method:

  • All actions are now executed asynchronously by default. You can override this and execute actions sequentially by passing parallel: false to the SDK.callAction argument or integration action.

  • All cookie handling methods are now asyncronous and compatible with cookieHandlingOverride.

  • On the Page object, the state property is now more verbosely typed as "default" | "published" | "draft" | "scheduled".

  • All get, set, and #privateProperty syntax was replaced with classic TypeScript private modifiers and design patterns, which improves compatibility with libraries such as React Native.

Bug fixes

  • In the Page type, the sections property was changed from a Section array to an object with optional footer, head, and main properties of a Section type.
  • In the page API, the getPage method now returns a union type of PageResponse|RedirectResponse type instead of only a PageResponse.
  • In the SDK.configure method, the extensionVersion argument is now correctly marked as required.
  • Error messages were improved and no longer contain repeated text.
  • In the event of a successful fetch with an unserializable response, the internal fetcher now catches and reports an error, as expected.