Extensions

We provide 3 types of extensions:

  • A data source is used to provide data to a page that can be configured by studio users
  • An action allows you to perform arbitrary API requests through our API hub
  • The dynamic page handler gives you the power to resolve the page folder URLs dynamically

Any such extension is implemented in JavaScript (or preferably TypeScript) and run in the API hub extension runner.

This article explains the basics for extension development which apply to all extension types. If you're familiar with this process, you can dig deeper into developing individual extension types:

Developing a data source extension
Developing an action extension
Developing a dynamic page extension

We currently support Node 14.

Defining extensions

The API hub extension runner expects a single JavaScript file to be run, which includes the full code (including all required library dependencies). We provide you with a pre-configured file packages/<project>/backend/index.ts in your GitHub customer repository.

This JavaScript file default-exports a standardized object that configures functions to be run as extensions. The object keys define the extension type and an identifier for the extension. For example:

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

Here, you can see the handler functions assigned for each extension type without going into detail on the corresponding extension. These details are explained in the detailed extension type documentation.

Developing extensions

Prerequisites

The extension development process works like this:

  1. You edit an extension source file locally
  2. A build process picks up this change and creates a new build instantly
  3. If the build is successful, it's synchronized to your sandbox
  4. The API hub extension runner picks up the change instantly
  5. You can now trigger the corresponding extension depending on the extension type

To start the extension build process, execute the following commands on your shell in the root directory of your Git repository:

frontastic init

The init command will ask you for the hostname of your sandbox (for more information, see the sandbox article).

frontastic run

The run command will start the build processes and bring you to the CLI dashboard with all relevant information:

8a26fda cli dashboard

Using the hotkeys, press the b key to show the build log of your extensions:

9e02362 backend logs

This example shows a successful build. The build process is automatically re-triggered whenever you change any source file in your extension.

Using the f hotkey, you can see the synchronization log up to your sandbox. An empty screen here (or no red number for it on the dashboard) means that synchronization works flawlessly.

b916d53 filesync logs

Using the s hotkey, you can see all the logs from your sandbox. You can see any errors that occur in the runner, information about when your extension build is reloaded (after every re-compile), when an extension is executed, and also any console.log calls from your extensions during execution:

832953e sandbox logs

Compiling extensions

The compilation mechanism for extensions can be chosen freely under 1 constraint: The output must be a single JavaScript file that was compiled to be run in Node.js.

If you're using the extension library, there's a pre-configured, minimal webpack build process in place that's automatically started through CLI.

Composable Commerce
Getting StartedMerchant CenterTutorialsHTTP APIGraphQL APIImport & ExportSDKs & Client LibrariesCustom Applications
Frontend
Getting StartedStudioDevelopingHTTP API
Sign upLog inSupportStatusOfferingTech BlogIntegrationsUser Research Program
Copyright © 2023 commercetools
Privacy PolicyImprint