Developing integrations for version 2 of the Frontend SDK

Custom integrations with commercetools Frontend include both backend and frontend development:

• Backend extension API: consists of a default export with the required actions, data-sources, and dynamic-page-handler methods merged with the other required integrations.
• Frontend SDK integration: consumes and utilizes the @commercetools/frontend-sdk package to call backend actions and handle events.

You must develop actions on the backend extension so that frontend SDK integrations can call them. For ease of development and debugging, we recommended developing the backend extension and frontend integration at the same time.

Create the SDK integration

Implement the SDK integration

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.

SDK integration example

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

type MyCustomEvents = {
  emptyCartFetched: { cartId: string };
};

type MyFirstActionPayload = {
  account: {
    email: string;
  };
};

type MyFirstActionQuery = {
  name: string;
};

type MyFirstAction = (
  payload: MyFirstActionPayload,
  query: MyFirstActionQuery,
  options: { serverOptions?: ServerOptions } = {}
) => Promise<SDKResponse<Cart>>;

class MyIntegration extends Integration<MyCustomEvents> {
  private myFirstAction: MyFirstAction = (
    payload: MyFirstActionPayload,
    query: MyFirstActionQuery,
    options: { serverOptions?: ServerOptions } = {}
  ) => {
    return this.sdk.callAction({
      actionName: 'example/myAction',
      payload,
      query,
      serverOptions: options.serverOptions,
    });
  };

  example: {
    myFirstAction: MyFirstAction;
  };

  constructor(sdk: SDK<MyCustomEvents>) {
    super(sdk);

    this.example = {
      myFirstAction: this.myFirstAction,
    };
  }
}

export { MyIntegration, MyCustomEvents };

How the SDK integration example works

In this code example:

• 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.
• 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.
• 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>.
• 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 }.
• 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.
• 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 associationts

  export default {
    'dynamic-page-handler': { ... },
    'data-sources': { ... },
    actions: {
      example: {
        myAction: <function to be called>
      }
    }
  }
  
• 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.
• 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.
• 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.

SDK response 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.

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

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);
  };
}, []);

Optimize event performance

To ensure high performance, the SDK automatically skips processing for events that don't have any registered handlers. This optimization is available in SDK version 2.1.0 and later.

Although the SDK handles internal skipping, you can use the following pattern to manually check for active handlers to avoid expensive data preparation costs in high-frequency integrations:

if (sdk.hasEventHandlers('productAddedToCart')) {
  const eventData = prepareEventData(product, quantity);
  sdk.trigger(
    new Event({
      eventName: 'productAddedToCart',
      data: eventData,
    })
  );
}

Trigger custom events

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;
};