# Extensions overview

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

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

Extensions are JavaScript/TypeScript functions that run on the [extension runner](/frontend-development/extensions.md#extension-runner) inside the API hub. commercetools Frontend supports the following types of extensions:

- [Data sources](/frontend-development/developing-a-data-source-extension.md): provide data to be displayed on a page through Frontend components.
- [Actions](/frontend-development/developing-an-action-extension.md): let you perform API requests using HTTP endpoints.
- [Dynamic page handler](/frontend-development/developing-a-dynamic-page-extension.md): 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](/frontend-development/developer-guide.md).

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

```typescript title="Example of backend/index.ts file"
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](/frontend-development/developing-your-site.md). The extension development process works as follows:

1. You edit an extension source file locally. This can be the `backend/index.ts` or any file imported inside of it.
2. The webpack file watcher detects the change and rebuilds the project.
3. If the build is successful, it is synchronized to the extension runner with your [developer API token](/frontend-development/developing-your-site.md#get-your-api-token-from-the-studio).
4. 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.

```shell title="Start extension development"
frontastic run
```

This command starts the build processes and opens the [CLI dashboard](/frontend-development/cli.md#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](/frontend-development/cli.md).

## Extension build process

A pre-configured [webpack](https://webpack.js.org/) build process automatically starts when you run `frontastic run` from the [CLI](/frontend-development/cli.md). The extensions run on the extension runner and are synchronized automatically after file save during development.

## Extension runner

The extension runner is a Node.js environment within the API hub that runs your [Data sources](/frontend-development/development-concepts.md#data-sources), [Actions](/frontend-development/development-concepts.md#actions), and [Dynamic page handler](/frontend-development/development-concepts.md#dynamic-pages) extensions.

The hostname to contact the extension runner has the following structure:

- For the production environment: `PROJECT_NAME-COMPANY_NAME.frontastic.live` (for example, `exampleshop-examplecompany.frontastic.live`)
- For the staging environment: `PROJECT_NAME-COMPANY_NAME.frontastic.io` (for example, `exampleshop-examplecompany.frontastic.io`)
- For the development environment: `PROJECT_NAME-COMPANY_NAME.frontastic.rocks` (for example, `exampleshop-examplecompany.frontastic.rocks`)

## 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](/frontend-development/extensions.md#get-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](/frontend-development/frontend-sdk.md), set the `extensionVersion` parameter in [configuration](/frontend-development/using-the-frontend-sdk.md).

### Get your Studio developer username

To copy your Studio developer username, follow these steps:

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

## Related pages

- [Area overview page with navigation](/frontend-development.md)
- [Next page: Developing a data source extension](/frontend-development/developing-a-data-source-extension.md)
- [Search documentation and API specs](/search.md)