Create reusable extensions

In the tutorial and the pages above, you discovered what can you can achieve with an Atoti UI extension. You used the Atoti UI starter (see Setup), which is an extension itself. Here, you will discover how to create reusable extensions.

Why creating reusable extensions?

Extensions allow you to group and package your customizations. Once an extension is built, you can plug it into Atoti UI without having to write additional JavaScript code or to rebuild JavaScript modules.

For instance, suppose that you create two custom widgets and need to add them to multiple Atoti UI projects.

You could package your two widgets as an NPM module and have your UI projects depend on it. But with this approach, it becomes cumbersome to release evolutions: you have to release the module containing your widgets, upgrade it in all projects, rebuild your projects and redeploy them.

To avoid this, you can package your two widgets as an Atoti UI extension instead. Then releasing an evolution becomes simpler: you just have to build the new version of your extension and deploy it within your running project.

How to split customizations into extensions?

You should limit the number of extensions plugged to your Atoti UI to a minimum. In particular, you should NOT create an atomic extension for each of your customizations. It is good practice to group customizations that you know will be used together into a single extension.

warning

Each extension is loaded into your user's browser and registered individually, causing an overhead in page loading time.

Create an extension

To create an extension, first create a new NPM module:

npm init

Then install @activeviam/activeui-scripts and @activeviam/activeui-sdk:

npm install @activeviam/activeui-scripts @activeviam/activeui-sdk

Add the following build script to your package.json:

  "build": "activeui-scripts build:extension"

Create a file named tsconfig.json with this content:

{
  "include": ["./src"]
}

Create a folder named src and a file index.ts inside it, with this content:

import { ExtensionModule } from "@activeviam/activeui-sdk";

const extension: ExtensionModule = {
  async activate(configuration) {
    configuration.applicationName = "Hello there!";
  },
};

export default extension;

note

This is a very basic Atoti UI extension example. For more advanced ones, read the documentation pages above and go through the tutorial.

Finally, build your extension:

npm run build

This will create the build of your extension in a folder named dist.

Plug an extension

Extensions can be plugged into the build folder of an Atoti UI project, whether it is a vanilla activeui-starter downloaded from the ActiveViam Artifactory or the build folder of a project bootstrapped from the activeui-starter-source, downloaded from the same place (see Setup).

tip

The build of your Atoti UI project contains a folder named extensions and a file named extensions.json.

Plug an extension manually

To plug your extension build into your project build manually, copy your extension's dist folder (see Create an extension) into your project's build/extensions folder.

Then rename this dist folder into your extension name, which is the name property in your extension's package.json.

Finally, edit the file extensions.json in order to add your new extension to it:

{
  "@activeviam/starter": "extensions/@activeviam/starter/@activeviam/starter.js",
  "my-extension": "extensions/my-extension/my-extension.js"
}

Your extension is plugged and accessible to your users.

Note that if your extension is a scoped NPM module (its name is in the form @foo/bar), then the content of its dist folder will look like:

• dist
  • @foo
    • bar.js

In this case, you must create the following folder structure when copying it into build/extensions:

• build
  • extensions
    • @foo
      • bar
        • @foo
          • bar.js

And your extensions.json must look like this:

{
  "@activeviam/starter": "extensions/@activeviam/starter/@activeviam/starter.js",
  "@foo/bar": "extensions/@foo/bar/@foo/bar.js"
}

Plug an extension using commands

If you maintain a project bootstrapped with the activeui-starter-source, you might find that copying extensions manually into its build folder is cumbersome, because this folder is cleaned up each time you run your start or build scripts.

In this situation, you can install the extension as a dependency of your project:

npm install my-extension

Update the start script in your package.json:

  "start": "activeui-scripts start --extensions . my-extension"

Similarly, update your build script:

  "build": "activeui-scripts build --extensions . my-extension"

This way, these scripts will copy your extension into your build folder, so that you don't have to do it manually.