Extensions

Extensions let you connect with external APIs, perform mutations, and render dynamic pages.

We currently support Node.js version 18.x for extensions. Other versions greater than or equal to 16.14 are also supported, but not recommended.

Extensions are JavaScript/TypeScript functions that run on the extension runner inside the API hub. commercetools Frontend supports the following types of extensions:

Data sources: provide data to be displayed on a page through Frontend components.
Actions: let you perform API requests using HTTP endpoints.
Dynamic page handler: lets you resolve the page folder URLs dynamically and render content dynamically based on the path.

External calls made by extensions have a timeout limit of 8 seconds to ensure optimal performance of the extension runner.

Define extensions

The API hub extension runner expects a single JavaScript file to run including all dependencies. You can find a pre-configured file at this path packages/<project-name>/backend/index.ts in your GitHub customer repository.

In the JavaScript file, default export is used to export a standardized object that configures functions to run as extensions. The object keys define the extension type and an identifier for the extension. The following example defines:

Two data source extensions: content/blog-list and content/blog-body
Four action extensions: cart/add, cart/remove, account/login, and account/logout.
The dynamic-page-handler extension

Example of backend/index.ts filetypescript

export default {
  'data-sources': {
    'content/blog-list': function () {
      /* ... */
    },
    'content/blog-body': function () {
      /* ... */
    },
  },
  actions: {
    cart: {
      add: function () {
        /* ... */
      },
      remove: function () {
        /* ... */
      },
    },
    account: {
      login: function () {
        /* ... */
      },
      logout: function () {
        /* ... */
      },
    },
  },
  'dynamic-page-handler': function () {
    /* ... */
  },
};

Develop extensions

Before developing extensions, ensure you have set up your project. The extension development process works as follows:

You edit an extension source file locally. This can be the backend/index.ts or any file imported inside of it.
The webpack file watcher detects the change and rebuilds the project.
If the build is successful, it is synchronized to the extension runner with your developer API token.
The API hub extension runner detects the change and runs the latest code on the next execution.

To start the extension development, run the following command on your command-line tool in the root directory of your project repository.

Start extension developmentshell

frontastic run

This command starts the build processes and opens the CLI dashboard from where you can monitor the extension logs as follows:

Press the b key to see the build log of your extensions.
Press the e key to see the execution logs of your extensions running on the extension runner. The logs include run time errors, console.log calls from the extensions during execution, information about the upload of the extension build after recompile, and information about the execution of extensions.

For more information about developing using the CLI, see CLI.

Extension build process

A pre-configured webpack build process automatically starts when you run frontastic run from the CLI. The extensions run on the extension runner and are synchronized automatically after file save during development.

Extension version

Requests to the extension runner must include the Commercetools-Frontend-Extension-Version HTTP header set to one of the following:

For the development environment: your Studio developer username.
For the production or staging environment: the NEXT_PUBLIC_EXT_BUILD_ID environment variable.

When making calls using the commercetools Frontend SDK, set the extensionVersion parameter in configuration.

Get your Studio developer username

To copy your Studio developer username, follow these steps:

From the Studio home page, click the Account icon and select Profile: the User settings dialog opens.
Copy the value in the Developer header username field.