Developing integrations for version 2 of the Frontend SDK

Create the SDK integration

Create a folder for your SDK integration in your commercetools Frontend project inside packages/PROJECT_NAME/frontend/src/sdk. If this folder does not exist, your project might predate the addition of the commercetools Frontend SDK. In such cases, please refer to the installation and setup instructions for the coFE SDK.

When developing an SDK integration, we recommend you keep the base SDK (@commercetools/frontend-sdk) package dependency up to date with the latest release. Updating the base SDK ensures you have access to the latest features and enhancements. After you complete the integration, you do not need to continuously update the dependency, however, we recommend you periodically check for new features, improvements, and bug fixes.

Implement the SDK integration

The main export of an SDK integration is a class that extends the Integration abstract class, which is imported from @commercetools/frontend-sdk.

The SDK integration must take the SDK singleton in the constructor and store the instance as a property. For example, the frontend-composable-commerce Integration class follows the same pattern. Following this structure provides consistency and ease of use, especially for SDK integrations with many methods and action type domains.

The Integration abstract class also defines the CustomEvents generic type to extend the BaseEvents type, which is of type Events.

Even if you don't need to define any custom events for an SDK integration, we recommend you create and export an empty type from your integration to let you define custom events in the future. If you don't create types for your custom events, compilation errors will occur. Failure to export this type will also cause errors when adding event handlers for these events, and when adding triggers within your SDK integration.

In the following code example, we implement an SDK integration. In the sample action, the return type is Cart from the coFE domain types at packages/PROJECT_NAME/types. For complete type-safety, the commerce types should be mapped to the domain types on the backend.

import {
  SDK,
  Integration,
  SDKResponse,
  ServerOptions,
} from '@commercetools/frontend-sdk';
import { Cart } from '@types/cart/Cart';

/**
 * Define a type for the integration's custom events, this will be exported
 * from the project index along with the integration. This type is used in
 * the generic argument of the SDK and Integration.
 */
type MyCustomEvents = {
  emptyCartFetched: { cartId: string };
};

/**
 * Define a type for the payload your action will take, this will be sent
 * in the body of the request (optional).
 */
type MyFirstActionPayload = {
  account: {
    email: string;
  };
};

/**
 * Define a type for the query your action will take, this will be appended to
 * the URL of the request (optional).
 */
type MyFirstActionQuery = {
  name: string;
};

/**
 * Define a type for the action, typing this action takes advantage of the
 * generic nature of the SDK's callAction method and lets the user know the
 * return type.
 */
type MyFirstAction = (
  payload: MyFirstActionPayload,
  query: MyFirstActionQuery,
  options: { serverOptions?: ServerOptions } = {}
) => Promise<SDKResponse<Cart>>;

/**
 * Define the class and extend the SDK's abstract Integration class, passing
 * along the MyCustomEvents type
 */
class MyIntegration extends Integration<MyCustomEvents> {
  /**
   * Define your action, ensuring explicit types, this will tell the user
   * the return type and required parameters, using the generic behavior
   * of the callAction method on the SDK.
   */
  private myFirstAction: MyFirstAction = (
    payload: MyFirstActionPayload,
    query: MyFirstActionQuery,
    options: { serverOptions?: ServerOptions } = {}
  ) => {
    /**
     * Return the call of the SDK callAction method by passing the
     * action name (the path to the backend action), the payload,
     * the query, and serverOptions to support SSR cookie handling.
     */
    return this.sdk.callAction({
      actionName: 'example/myAction',
      payload,
      query,
      serverOptions: options.serverOptions,
    });
  };

  // Define the type of the example domain object.
  example: {
    myFirstAction: MyFirstAction;
  };

  /**
   * Define the constructor with the SDK singleton as an argument,
   * passing the MyCustomEvents type again.
   */
  constructor(sdk: SDK<MyCustomEvents>) {
    // Call the super method on the abstract class, passing it the SDK.
    super(sdk);

    /**
     * Initialize any objects with defined methods. This pattern
     * improves user experience for complex integrations because actions
     * are called in the format sdk.<integration>.<domain>.<name>.
     */
    this.example = {
      myFirstAction: this.myFirstAction,
    };
  }
}

// Export the integration to be imported and exported in the package index.
export { MyIntegration, MyCustomEvents };

In this code example:

1. The MyCustomEvents type is based on the base SDK's Events. In practice, we recommended you to define the type in another file for readability reasons.

2. The MyFirstActionPayload type defines the action's optional payload argument. This type defines what must be passed into the integration's action call, which is serialized into the body of the request. It must be an object of type AcceptedPayloadTypes.

3. The MyFirstActionQuery type defines the action's optional query argument. It must be an object of type AcceptedQueryTypes, which accepts any serializable JSON type. This query is appended to the URL of the action call. Following the example, it would be <endpoint>/frontastic/example/myAction?name=<nameValue>.

4. The MyFirstAction type defines the type of the action function. The parameters typed with the MyFirstActionPayload and MyFirstActionQuery arguments, and the return type of Promise<SDKResponse<Cart>> are specified. By specifying the return of SDKResponse with the Cart generic argument, the generic argument of the SDK's callAction method is defined and made type-safe. This way, the integration user knows on a successful action call they will have a return type of { isError: false, data: Cart }.

5. The MyIntegration class extends the base SDK's Integration abstract class, and passes the MyCustomEvents type to the generic argument. This lets you trigger and/or add event handlers for custom events as well as the base SDK's StandardEvents commerce types. To interact with another integration's custom events, you must import its events and add the type to the generic argument with an intersection.

6. The myFirstAction function is defined with the MyFirstAction type. The function is marked as private so it cannot be called directly on the class. However, in practice, this will likely be defined elsewhere and set up externally. For an example on how these actions can be set up, see the constructor of the Composable Commerce integration within your project at packages/PROJECT_NAME/frontend/sdk/composable-commerce/library/Integration.ts, or packages/PROJECT_NAME/frontend/src/sdk/composable-commerce-b2b/library/Integration.ts for B2B projects. \

   On the return of this method, the SDK's callAction method is returned, passing the actionName, payload, and query. The actionName will match the backend's default export action structure, for actionName: 'example/myAction' the default export will call the following action on the backend.

   example/myAction actionName backend associationTypeScript

   export default {
     'dynamic-page-handler': { ... },
     'data-sources': { ... },
     actions: {
       example: {
         myAction: <function to be called>
       }
     }
   }

7. The type of the example object is defined, where the methods for the actions in the example domain are also defined. Structuring the methods in this way creates a tree structure for callable methods. For example, a typical commerce integration might have account, cart, product, and wishlist domains for actions. Therefore, by structuring the methods in this way, it is easier to find the methods to be called. An example of the domain can be found in the composable-commerce integration in the CartActions.

8. The constructor is defined with the sdk singleton passing the MyCustomEvents as a generic argument. This lets you trigger and/or add event handlers for custom events as well as the base SDK's BaseEvents. To interact with another integration's custom events, you must import its events and add the type to the generic argument with an intersection. Then, the super keyword is used to invoke the constructor of the abstract base class passing it the sdk. Finally, the example domain object is set up with the this.myFirstAction method definition.

9. The MyIntegration and MyCustomEvents types are exported and imported to the package's index file. From there, they are exported to be imported into your commercetools Frontend project.

In this example, the return type is Promise<SDKResponse<Cart>>. The response from the SDK can be of following types:

• SDKResponse type from the base SDK.
• { isError: false, data: T } on success, where the T type is generic and defines the type of data fetched on success, which you can specify by passing the type to the SDK’s callAction method (sdk.callAction<T>) as the generic argument.
• { isError: true, error: FetchError } on error.

For a full scale example of a structured integration, see the composable-commerce integration.

Implement event handling

The commercetools Frontend SDK comes with the event engine that lets integrations add event handlers and communicate with other integrations by triggering events.

Add and remove event handlers

The following code is an example of adding and removing an event handler by calling the on and off methods.
First, the emptyCartFetched event handler callback is defined.
Then in the useEffect React lifecycle hook, the on method is called on component mounting.
Finally, a function calling the off method on component unmounting is returned to clean up.

The emptyCartFetched named function is defined to serve as the eventHander parameter. The event argument type of Event<EventName, EventData> must be fully typed for the SDK to accept the handler argument along with "emptyCartFetched" as the value of the eventName parameter.

const emptyCartFetched = (
  event: Event<
    'emptyCartFetched',
    {
      cartId: string;
    }
  >
) => {
  // Access event.data.cartId in the body of the event handler.
};

useEffect(() => {
  sdk.on('emptyCartFetched', emptyCartFetched);
  return () => {
    sdk.off('emptyCartFetched', emptyCartFetched);
  };
}, []);

This example sets up an event handler with a lifecycle scoped to a single React component. To avoid duplicate handlers when the component remounts, the off method is called within the cleanup function of useEffect. Without this cleanup, the handler would be added each time the component mounts, potentially causing memory leaks or unintended behavior.
For event handlers that should persist beyond a single component's lifecycle, such as those tied to the lifespan of the application, integration users can call the on method within the SDK template constructor. To attach persistent handlers directly within the SDK integration, call the on method in the SDK integration’s constructor and pass an anonymous function.

Trigger custom events

The following code is an example of triggering an event by calling the trigger method.
First, the getCart action is defined, for which a response is returned by the sdk.
Then, the isError parameter is checked to see if the action has errored and the trigger method is called to trigger the standard cartFetched event.
Finally, if the cart is empty, the trigger method is called to trigger the emptyCartFetched event.

getCart: async () => {
  const response = await sdk.callAction<Cart>({
    actionName: 'cart/getCart',
  });

  if (response.isError === false) {
    sdk.trigger(
      new Event({
        eventName: 'cartFetched',
        data: {
          cart: response.data,
        },
      })
    );

    if (!response.data.lineItems || response.data.lineItems.length === 0) {
      sdk.trigger(
        new Event({
          eventName: 'emptyCartFetched',
          data: {
            cartId: response.data.cartId,
          },
        })
      );
    }
  }
  return response;
};