@i2analyze/create-notebook-plugin

The Create Notebook Plug-in package provides a simple way to bootstrap development of i2 Analyst's Notebook web client plug-ins. It generates a build environment that's configured with development proxy support and production bundling for plug-in deployment.

Quick start

To create the environment quickly, run the following commands at a command prompt to generate a basic plug-in project:

> npx @i2analyze/create-notebook-plugin
Plug-in name: My plug-in
Plug-in description: My i2 Notebook plug-in
Run git init?: yes
Run npm install?: yes
> cd my-plug-in
> npm run dev

A development server starts, serving your plug-in at http://localhost:8080/opal/plugins/[plugin-name]. The notebook-sdk-plugin-proxy is also started, proxying to a server located at http://localhost:9082/opal/.

Prerequisites and options

To use the Create Notebook Plug-in package, i2 recommends that Node.js version 20 or later is installed on your development workstation. You can use Volta to install and switch versions of Node.

To create a basic plug-in project, you can choose any of the following methods.

npx

npx @i2analyze/create-notebook-plugin

npm

npm init @i2analyze/notebook-plugin

yarn

yarn create @i2analyze/notebook-plugin

Note: No matter how you create it, the generated plug-in project uses npm as its package manager.

Selecting a template

By default, create-notebook-plugin creates a basic plug-in with an entrypoint.ts file but no user interface. You can create a plug-in from a different template by appending --template=[template-name] to the creation command.

The available templates are:

• --template=plugin

  The default, basic plug-in template.

• --template=plugin-with-toolview

  A basic plug-in with a single tool view that displays a simple HTML page. The plug-in uses React as the front-end framework and contains a single ToolView component.

Note: When using npm commands with arguments, you must use the -- separator to pass arguments to the package:

npm init @i2analyze/notebook-plugin -- --template=plugin-with-toolview

The -- separator is required because npm init and npm create need to distinguish between npm's own options and the package's arguments. Everything after -- is passed directly to the package.

CLI options

You can supply details of your plug-in on the command line when you run create-notebook-plugin. If you omit an option, the package prompts you for a value.

• --name=[plug-in name]

  The name of your plug-in.

• --description=[plug-in description]

  An optional description of your plug-in, which becomes the value of the description field in the package.json file.

• --git=[yes|no]

  Indicates whether to run git init in the plug-in folder after creation.

• --install=[yes|no]

  Indicates whether to run npm install in the plug-in folder after creation.

• --outDir=[path]

  The path to use as the plug-in folder. Defaults to the plug-in's name, converted to kebab-case.

Scripts

Inside the created plug-in folder, you can run some built-in script commands.

npm dev

Runs the plug-in in development mode and starts the notebook-sdk-plugin-proxy. You can change the proxy settings by editing the devproxy.json configuration file in the plug-in folder.

npm build

Builds a minified plug-in for production to the dist folder. You can copy the contents of the dist folder to an i2 Analyze deployment.