Plugin system

Table of contents

• Folder structure
• Commands
• Build plugin
• Build product
  • Commands
• Development
• Static assets
• Localization
• Creating a Custom Plugin

Folder structure

Plugin structure can be found on Frontend development guidelines

Commands

Execute from cloudbeaver/webapp
yarn run bootstrap

Load all dependencies and init workspaces
yarn run build

Build all packages (plugins and the application) and the result will be placed in the packages/{package-name}/lib folder
yarn run lint

Lint all code
yarn run lint-fix

Lint all code and fix

Build plugin

To build a single plugin execute

yarn lerna run build --stream --scope=@cloudbeaver/plugin-name

Build product

Product folder structure can be found on Frontend development guidelines
The only difference in the build command is:
"build": "core-cli-build --mode=production --config ../core-cli/configs/webpack.product.config.js",
it uses product config, also contains dev command for starting development local build
"dev": "core-cli-build serve --mode=development --progress --config=../core-cli/configs/webpack.product.dev.config.js",

The application package simple defines the list of plugins that should be included in the build

Commands

Execute the command to build only the application without rebuilding the plugins
yarn lerna run build --stream --scope=@cloudbeaver/product-name

Development

1. To run a development build that watches file changes and rebuilds, you can use the dev command:
   yarn lerna run dev --stream --scope=@cloudbeaver/product-default -- -- --env server=http://backend.server:8095
   It starts the dev server for product-default. It also proxies backend requests to http://backend.server:8095

2. Navigate localhost:8080 to open the application

Static assets

You can keep static assets like images, favicon, etc in the public folder in the plugin packages or app package.

Assets such as these will be copied to the application distributive. Assets with the same name will overwrite one another, but the Application public assets have higher priority over them all.

Localization

See the example in the core-administration AdministrationLocaleService.ts and locales folder

Creating a Custom Plugin

Follow these steps to create a custom plugin that adds a button to the top bar and logs "Hello, World!" to the console:

1. Create Plugin Folder

• Inside /webapp/packages, create a folder with your desired name, e.g., plugin-hello-world.

2. Copy Configuration Files

• Copy the following files from any existing package into your plugin folder:
  • .gitignore
  • package.json
  • tsconfig.json

3. Update package.json

• Open package.json and update the name field to your plugin's name, @cloudbeaver/plugin-hello-world.
• Remove the dependencies and devDependencies sections.

4. Update tsconfig.json

• Remove the references section from tsconfig.json.

5. Create Source Files

• Inside your plugin folder, create a src folder.
• Add two files in src:
  1. index.ts
  2. manifest.ts
• Export the manifest from index.ts:

  export * from './manifest.js';

6. Create a Service

• Create a service to add the button.
• It should:
  • Be an injectable class.
  • Extend the Bootstrap class.
• Add a register method and implement the button-adding logic.

Example:

import { Bootstrap, injectable } from '@cloudbeaver/core-di';
import { ActionService, MenuService } from '@cloudbeaver/core-view';
import { MENU_APP_ACTIONS } from '@cloudbeaver/plugin-top-app-bar';

import { ACTION_HELLO_WORLD } from './ACTION_HELLO_WORLD.js';

@injectable()
export class HelloWorldService extends Bootstrap {
constructor(
 private readonly actionService: ActionService,
 private readonly menuService: MenuService,
) {
 super();
}

override register(): void {
 this.menuService.addCreator({
   menus: [MENU_APP_ACTIONS],
   getItems: (context, items) => [...items, ACTION_HELLO_WORLD],
 });

 this.actionService.addHandler({
   id: 'hello-world-handler',
   actions: [ACTION_HELLO_WORLD],
   handler: (context, action) => {
     switch (action) {
       case ACTION_HELLO_WORLD: {
         console.log('Hello World!');
         break;
       }
     }
   },
 });
}
}

import { createAction } from '@cloudbeaver/core-view';

export const ACTION_HELLO_WORLD = createAction('hello-world', {
 label: 'Hello world!',
});

7. Register the Service

Register your service in manifest.ts like this:

import type { PluginManifest } from '@cloudbeaver/core-di';

export const helloWorldPlugin: PluginManifest = {
  info: {
    name: 'Hello World Plugin',
  },
  providers: [() => import('./HelloWorldService.js').then(m => m.HelloWorldService)],
};

8. Connect Plugin to Product

Open /webapp/packages/product-default/index.ts and include your new plugin:

import { helloWorldPlugin } from '@cloudbeaver/plugin-hello-world';

const PLUGINS: PluginManifest[] = [
  ...existingPlugins,
  helloWorldPlugin,
];

9. Run commands

In /webapp, run:

yarn run update-ts-references
yarn
yarn run update-ts-references

Now, your button should appear in the top bar and log "Hello, World!" when clicked.