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.

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 associationts

   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.

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

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