Extensions

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

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:

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

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.

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:

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.