Frontend SDK and CLI

Frontend SDK version 2.0.0

Version 2.0.0 of the Frontend SDK brings several updates, including breaking changes, new features, and bug fixes. Following are the most important changes.

Breaking changes

The latest SDK update contains several breaking changes, bringing adjustments and improvements to streamline usage and maintain consistency:

• Commerce-related events are now in the Composable Commerce integration, making them easier to manage. The Page API underwent significant changes; among these, the getPage method now returns a union type of PageResponse and RedirectResponse instead of just PageResponse.

  getPage: (options: {
          path: string;
          query?: AcceptedQueryTypes;
          customHeaderValue?: string;
          serverOptions?: ServerOptions;
      }) => Promise<SDKResponse<PageResponse | RedirectResponse>>;
  
• We restructured the sections property in the Page type. Previously, it was an array of Section objects, while now it's an object with optional footer, head, and main properties of type Section. Additionally, the state property in the Page type now accepts specific values: default, published, draft, or scheduled. To ensure consistency, all Page API and event-related types are now defined as interfaces.

  import { Section } from "@frontastic/extension-types";
  
  export interface Page {
      pageId: string;
      sections: {
          footer?: Section;
          head?: Section;
          main?: Section;
      };
      state: "default" | "published" | "draft" | "scheduled";
  }
  
• The SDK methods underwent some changes too:
  • In SDK.configure, the extensionVersion argument is now required.

  type SDKConfig = {
     locale: string;
     currency: Currency;
     endpoint: string;
     extensionVersion: string;
     useCurrencyInLocale?: boolean;
     sessionLifetime?: number;
     cookieHandlingOverride?: CookieManager;
     redactionHandlingOverride?: RedactionManager | RedactionManagerConfig;
     customHeaderValue?: string;
  };
  
  • For SDK.callAction, we replaced the skipQueue parameter with an optional parallel argument, which defaults to true.

  * @param {boolean} [options.parallel] - An optional boolean, default true indicating whether the action should executed asynchronously or be added to a queue and executed in sequence. Useful to supply false on actions you may think have race conditions.
  
  async callAction<ReturnData>(options: {
          actionName: string;
          payload?: AcceptedPayloadTypes;
          query?: AcceptedQueryTypes;
          parallel?: boolean;
          customHeaderValue?: string;
          serverOptions?: ServerOptions;
      }): Promise<SDKResponse<ReturnData>>
  
• Cookie handling is now fully asynchronous and we removed the previous synchronous cookie handling. The rememberMeCookieAsync object was renamed to rememberMeCookie and now serves as the default.
• Several classes and properties were deprecated or removed:
  • The Integration class replaced the Extension one.
  • Properties like posixLocale and methods such as endpoint, locale, currency, and customHeaderValue are now deprecated.
  • Event class properties, including isDefaultPrevented, isCancelled, and isPropagationStopped are also deprecated.
• For event handling, the Event class no longer includes properties like isDefaultPrevented, isCancelled, and isPropagationStopped. The payload argument in SDK.callAction must now be of type AcceptedPayloadTypes.

  async callAction<ReturnData>(options: {
          actionName: string;
          payload?: AcceptedPayloadTypes;
          query?: AcceptedQueryTypes;
          parallel?: boolean;
          customHeaderValue?: string;
          serverOptions?: ServerOptions;
      }): Promise<SDKResponse<ReturnData>>
  
• Error handling was also updated:
  • The FetchError class now accepts an options argument with an error property of type string | Error.
  • The ActionError class no longer includes the actionName property and now requires a single options argument.
  • Similarly, the PageError class no longer contains the path property and only accepts an options argument with an error property of type string | Error.

New features

We introduced some exciting features to the SDK, bringing more flexibility and functionality:

• The BaseEvents file now replaces StandardEvents and contains several new events. For example, actionCalled triggers when an action is called, while pageApiMethodCalled triggers when a Page API method is called. Also, fetchCalled activates when you call an action or a Page API method. On top of that, you’ll find events like actionFetchSuccessful, fetchSuccessful, and pageApiFetchSuccessful to indicate successful responses. Errors are handled too, with actionErrorCaught and pageApiErrorCaught capturing issues during operations.
• Redaction handling is enhanced too. Sensitive JSON and URL data is now automatically redacted in internal events. If you need a different behavior, you can override this default with redactionHandlingOverride in SDK.configure.
• Another big update is asynchronous execution. Actions now run asynchronously by default, but you can switch to synchronous behavior by setting parallel: false in SDK.callAction. Cookie handling is now fully asynchronous and works seamlessly with cookieHandlingOverride.

  type SDKConfig = {
      locale: string;
      currency: Currency;
      endpoint: string;
      extensionVersion: string;
      useCurrencyInLocale?: boolean;
      sessionLifetime?: number;
      cookieHandlingOverride?: CookieManager;
      redactionHandlingOverride?: RedactionManager | RedactionManagerConfig;
      customHeaderValue?: string;
  };
  

Enhancements and bug fixes

We released enhancements and bug fixes to improve the SDK’s reliability and functionality:

• The Page API is enhanced with updates to the sections property and the getPage method, ensuring they align with the latest response types. In the SDK.configure method, the extensionVersion argument is now properly marked as required, addressing a previous inconsistency.
• We also improved Error handling by removing repetitive text from error messages, making them clearer and easier to understand. Additionally, the internal fetcher now catches and reports errors for responses that can’t be serialized, making troubleshooting more straightforward.

Developer experience improvements

We optimized the Frontend SDK for ease of use and extensibility:

• Multi-tenancy projects are now easier to manage. The new extensionVersion configuration option in the SDK.configure method lets you specify the version of the extension bundle that you want to connect to in multi-tenant setups, thus streamlining the process. For session management, a new sessionLifetime option is now available. This gives developers more control by allowing them to adjust the default session duration based on their needs.

  type SDKConfig = {
      locale: string;
      currency: Currency;
      endpoint: string;
      extensionVersion: string;
      useCurrencyInLocale?: boolean;
      sessionLifetime?: number;
      cookieHandlingOverride?: CookieManager;
      redactionHandlingOverride?: RedactionManager | RedactionManagerConfig;
      customHeaderValue?: string;
  };
  
• In terms of types and composability, we aimed at simplifying things. We encourage you to abandon the older @commercetools/frontend-domain-types and @commercetools/frontend-composable-commerce packages. Instead, you can now reference types and SDK integrations directly within your project’s folder structure for a cleaner setup.
• Cookie handling got more customizable. You can now use the cookieHandlingOverride option to extend or override the default cookie behavior. This gives you better control to manage cookies across various environments.

CLI updates (version 2.4.2)

We updated the CLI, fixing some issues and improving the overall behavior:

• Installation issues have been addressed. If Yarn isn’t detected, the CLI now gives you clear installation instructions instead of letting you know it’s missing. Log view readability has also improved as long messages no longer spill over the right border, making it much easier to read.
• We also have good news about uploads. The CLI now properly handles uploading backend extensions in newly cloned repositories without needing a restart. Validation is tighter because the GUID validation pattern in the code generator is now more precise. Additionally, if you run into errors while copying log messages, errors will now appear in a dialog to make troubleshooting more straightforward.
• We made a handy change for project initialization. You no longer need to include the --multitenant parameter when running the frontastic init command. That’s one less thing to worry about.

Test your knowledge