Create a JavaScript plugin

This guide covers creating JavaScript (JS) plugins that extend the Deephaven web UI with custom React components. For server-side plugins, such as plugins that register object types or add custom RPC methods to the Python client API, see Create your own plugin.

The Deephaven server serves each registered JS plugin's JavaScript, CSS, and other static assets, and the web UI loads those plugins when it starts.

Prerequisites

Before creating a JS plugin, you should be familiar with:

  • React and TypeScript/JavaScript
  • npm package management
  • Python packaging basics

When to create a JS plugin

Create a JS plugin when you need to:

  • Add custom visualization components to the Deephaven web UI.
  • Integrate third-party charting or UI libraries, such as D3 or Chart.js.
  • Create reusable UI components that you can share across projects.
  • Build components that require complex client-side interactivity.

If you only need custom UI for a single project without sharing, consider using deephaven.ui components directly.

Quick start with cookiecutter

The easiest way to create a JS plugin is with the cookiecutter templates from the deephaven-plugins repository:

This creates a complete project with Python registration, React scaffolding, and build configuration.

The element template creates an element plugin that extends deephaven.ui. An element plugin is the right choice for most plugins. If your plugin renders a server-side object that a server plugin registers, use --directory="templates/widget" instead to create a widget plugin.

The examples on this page use the layout that the cookiecutter templates generate:

  • src/js/ is the JavaScript project. package.json and the Vite configuration file are at its top, and the source is in src/js/src/.
  • src/my_plugin/ is the Python package.

The examples differ from the templates in these ways:

  • The templates split the entry point into src/js/src/index.ts and a separate plugin file. The element example on this page defines the plugin directly in src/js/src/index.tsx. The widget and MultiPlugin examples use separate plugin files, as the templates do.
  • The templates name the Vite configuration file vite.config.js. This page uses vite.config.ts.
  • The templates put the registration class in register.py, declare the entry point in setup.cfg, and copy the built JS into the package's _js directory. This page puts the registration class in src/my_plugin/__init__.py, declares the entry point in pyproject.toml, and copies the built JS into src/my_plugin/js.
  • The templates create the plugin with create_js_plugin from deephaven-plugin-utilities. This page subclasses JsPlugin so that each property is visible. See Python registration.

Write the plugin

The JavaScript side of a plugin is a React project whose main file exports a plugin object. This section covers the plugin types and how to export several plugins from one package.

Plugin types

The main file of a JS plugin must have a default export that the web UI can load. The source of that file is src/js/src/index.tsx, and the build writes it to src/js/dist/index.js. The Python registration names dist/index.js as the plugin's main file.

The default export is a plugin object that tells the web UI what kind of plugin it is and which React components to use. Every plugin object has these properties:

  • name: Identifies the plugin and must be unique.
  • type: One of the PluginType values from the @deephaven/plugin package. It determines which other properties the web UI expects.

The name that the web UI registers a plugin under depends on where the plugin object is:

  • The package's default export is registered under the name from the server registration, not its own name. The registration uses the package.json name, unless it sets a different one, as a JsPlugin subclass can. Set both to the package name.
  • A plugin inside a MultiPlugin is registered under its own name.

For the full set of properties each type accepts, see PluginTypes.ts in the web-client-ui repository.

TypePurpose
PluginType.ELEMENT_PLUGINMaps custom element names to React components for deephaven.ui.
PluginType.WIDGET_PLUGINRenders a server-side object in a panel. The supportedTypes property lists the server object types the plugin handles, and component renders them.
PluginType.DASHBOARD_PLUGINMounts a component once per dashboard. Use it to register custom panel types or respond to dashboard events.
PluginType.TABLE_PLUGINAdds a custom component to the panel of any table whose PluginName attribute is set to the name the plugin is registered under. Set the attribute on the server with with_attributes, for example t.with_attributes({"PluginName": "@my-org/my-plugin"}).
PluginType.THEME_PLUGINProvides one or more custom themes. See Custom themes.
PluginType.AUTH_PLUGINAdds a login method to the web UI.
PluginType.MIDDLEWARE_PLUGINWraps the component of a widget plugin to add behavior without replacing it. Requires Deephaven Community Core 41.7 or later (web UI 1.19.0 or later).
PluginType.MULTI_PLUGINBundles several of the plugins above into one package. See Register multiple plugins from one package.

The following src/js/src/index.tsx exports an element plugin, the kind of plugin the element cookiecutter template generates. Each key in mapping is an element name that a deephaven.ui component on the server refers to, and each value is the React component that renders it:

A widget plugin renders a server-side object directly. Its supportedTypes value must match the name of an object type registered on the server. If no plugin registers a matching object type, the widget plugin never renders anything.

Any server plugin can register that object type. It can be written in Python or Java, and it doesn't have to ship in the same package as the JS plugin. To register an object type, see Create your own plugin.

The following src/js/src/MyWidgetPlugin.tsx defines a widget plugin:

To use it as the package's only plugin, make it the default export of src/js/src/index.tsx:

Register multiple plugins from one package

A package's default export normally registers a single plugin. To register several plugins from one package, export a MultiPlugin instead. A MultiPlugin is a plugin object whose type is PluginType.MULTI_PLUGIN and that has a plugins array.

When the web UI loads the package, it registers each plugin in the array individually, under that plugin's own name. It doesn't register the MultiPlugin itself, so an inner plugin can reuse the MultiPlugin's name.

A MultiPlugin is useful when a package needs to:

  • Provide more than one kind of plugin, such as a widget plugin and a dashboard plugin.
  • Keep a legacy plugin registered for backward compatibility while adding a newer one. For example, a dashboard plugin can continue to open panels saved in existing dashboards while a widget plugin handles new ones.
  • Register several widget plugins, each with its own supportedTypes, title, or icon.

Note

MultiPlugin requires Deephaven Community Core 41.5 or later (web UI 1.17.0 or later). Earlier versions don't recognize the MultiPlugin type. In those versions, the web UI logs a "missing an exported value" error to the browser console and loads none of the plugins in the array.

The following src/js/src/index.tsx registers a widget plugin and a dashboard plugin from the same package. It imports the widget plugin from the MyWidgetPlugin.tsx file shown in Plugin types, and makes the MultiPlugin, rather than the widget plugin, the default export. This is the pattern the official plotly-express plugin uses:

Keep the following rules in mind:

  • Give every plugin in the plugins array a unique, non-empty name. A common convention is to append a suffix to the package name, such as @my-org/my-plugin.DashboardPlugin.
  • Make every entry in the plugins array an object.
  • Don't nest a MultiPlugin inside another MultiPlugin.
  • Keep the server registration unchanged. The Python registration still points to a single main file, and the MultiPlugin is that file's default export.

In Deephaven Community Core 41.7 or later (web UI 1.19.0 or later), the web UI checks only the type and name of each entry in the plugins array:

  • It skips an entry with an unrecognized type or an empty name and logs a warning to the browser console.
  • It never checks type-specific properties, such as component, so it registers an entry that lacks one.
  • An entry that isn't an object, such as null or a string, stops the web UI from loading any JS plugins, including plugins from other packages. The web UI logs an "Unable to load plugins" error to the browser console.

Build and register the plugin

A JS plugin typically consists of two parts:

  1. JavaScript bundle: Contains the React components and any other client-side code.
  2. Python package: Registers the plugin with the Deephaven server and specifies the directory that contains the JS assets.

A plugin that only contains JavaScript can skip the Python package and register through a server manifest instead. See Register without a Python package. During development, you can also point the server directly at the plugin's npm package directory. See Register an npm package directory during development.

Build configuration

Key requirements for the JS bundle:

  • Give the package a unique name. A scoped name like @my-org/my-plugin helps avoid collisions. Official Deephaven plugins use @deephaven/js-plugin-<name>.
  • Export as a CommonJS (CJS) bundle.
  • Externalize only the packages listed below, so that your plugin uses the same copies as the rest of the UI.

The web UI provides the following packages at runtime. The authoritative list is in remote-component.config.ts.

  • react, react-dom, redux, and react-redux
  • @adobe/react-spectrum
  • @deephaven/auth-plugins, @deephaven/chart, @deephaven/components, @deephaven/console, @deephaven/dashboard, @deephaven/dashboard-core-plugins, @deephaven/icons, @deephaven/iris-grid, @deephaven/jsapi-bootstrap, @deephaven/jsapi-components, @deephaven/jsapi-utils, @deephaven/log, @deephaven/plugin, and @deephaven/react-hooks

Warning

Don't externalize any other package, including other @deephaven/* packages, unless another JS plugin supplies it through the loader field. The web UI supplies only the packages listed above, so a plugin that externalizes any other package fails to load. Bundle those packages into your plugin instead.

The following src/js/package.json builds with Vite and declares the @deephaven/* packages that the examples on this page import:

The following src/js/vite.config.ts builds src/index.tsx into the CommonJS bundle dist/index.js and externalizes only packages that the web UI provides:

Python registration

The Python side uses deephaven.plugin.js.JsPlugin to register the plugin. This class tells the server where to find the JS assets. The following src/my_plugin/__init__.py defines the plugin and its registration:

The pyproject.toml must register the plugin as an entry point:

The path method returns the directory that contains the built JS bundle. In this layout, that directory is inside the Python package, so the JS ships with it.

Installing the Python package doesn't copy the JS on its own, so add a setup.py that copies it in with package_js from deephaven-plugin-packaging. Using the layout described in Quick start with cookiecutter, the following example packs src/js/ into src/my_plugin/js:

package_js runs npm pack on the JS project:

  • The copied directory contains package.json and the files listed in its files field.
  • If src/js/dist/ doesn't exist yet, package_js copies nothing, so build the JS first.

The cookiecutter templates already include an equivalent setup.py.

Instead of subclassing JsPlugin, the cookiecutter templates and the official plugins call create_js_plugin from the deephaven-plugin-utilities package, for example callback.register(create_js_plugin("my_plugin", "js")). The second argument names the package directory that contains package.json. create_js_plugin reads the name, version, and main file from that package.json, so they always match the JS build.

Use exports from another JS plugin

A package that the web UI doesn't provide and your plugin doesn't bundle can come from another JS plugin. In Deephaven Community Core 42.5 and later, add a loader field to the package.json file of each plugin:

  • In the other plugin's package.json, set the loader field's "package" value to its package name.
  • In your plugin's package.json, list that name in the loader field's "dependencies" array.

The web UI then loads that plugin first and supplies its exports to yours.

How the server gets the loader field depends on how you register the plugin:

  • npm package directory: The server reads the field from package.json.
  • Server manifest: pack-plugins.sh copies the field from package.json into manifest.json.
  • Python package with create_js_plugin: deephaven-plugin-utilities 0.1.0 and later read the field from package.json.
  • Python package with a JsPlugin subclass: Add a loader property that returns the same value, for example return {"dependencies": ["@my-org/other-plugin"]}.

Register without a Python package

If your plugin only contains JavaScript, you can skip the Python package. To register it, use the server manifest:

  1. Package the plugin with the pack-plugins.sh script from the web-plugin-packager Docker image, as shown in Configure JS plugins. The script extracts each npm package and writes a manifest.json file that lists them. If the plugin isn't published to npm:
    1. Build the plugin.
    2. Copy its npm package directory into the packager stage, for example COPY src/js /my-plugin.
    3. Pass the directory's absolute path to the script, for example RUN ./pack-plugins.sh /my-plugin. A path relative to the working directory doesn't work, because the script runs npm pack from a temporary subdirectory.
  2. Copy the contents of the generated js-plugins directory into the js-plugins/ subdirectory of the server's configuration directory, so that manifest.json is at <configDir>/js-plugins/manifest.json. Alternatively, set the deephaven.jsPlugins.resourceBase configuration property to the directory that contains manifest.json.

The server loads only the plugins listed in manifest.json, so copying an npm package into the directory by hand doesn't register it. See Configure JS plugins.

Development workflow

If you register the plugin with a Python package, use the following workflow:

  1. Build the JS: npm install && npm run build in src/js/.
  2. Install the Python package: pip install -e ./path/to/my-plugin. This runs setup.py, which copies the built bundle into the Python package.
  3. Start the server. The server registers the plugin at startup, and the web UI loads it.
  4. Iterate. After each change:
    1. Edit the JS code and rebuild it.
    2. Reinstall the Python package so it picks up the new bundle.
    3. Restart the Deephaven server. The server registers JS plugins only at startup, so it keeps serving the old bundle until you restart it.
    4. Refresh the web UI.

Register an npm package directory during development

To iterate without reinstalling a Python package or repackaging a server manifest, register the npm package directory directly:

  1. Remove any other registration of the same plugin. The server throws an error when two JS plugins have the same name.
    • If the package contains nothing but the JS plugin and its registration, uninstall it.
    • If the package also contains server-side code, keep it installed and temporarily remove the callback.register call for the JS plugin from its Registration class. Server-side code includes the deephaven.ui component from the element template and the object type from the widget template.
    • If you registered it through a server manifest, remove its entry from manifest.json.
  2. In the configuration file or as a JVM argument, set a deephaven.jsPlugins.<name> configuration property to the npm package directory, such as deephaven.jsPlugins.my-plugin=/path/to/my-plugin/src/js.
    • <name> can be any label that doesn't contain a ..
    • Don't use resourceBase as the label, because deephaven.jsPlugins.resourceBase sets the server manifest directory.
  3. Build the JS before you start the server. After each change, rebuild the JS, restart the server, and refresh the web UI.

The server reads the plugin's name, version, and main file from the directory's package.json. When the main file is in a subdirectory, the server serves only the main file's top-level directory, such as dist/ for dist/index.js.

To iterate without restarting the server, use a plugin development server and a development build of the web UI:

  1. Clone the deephaven-plugins repository and put your plugin in its plugins/ directory.
  2. Run the plugin development server from that clone. It rebuilds the plugins in plugins/ whenever you save a change, and serves them.
  3. Run a development build of the web UI from the web-client-ui repository, and point it at the plugin development server.

For the commands, see Building JS plugins for development in the deephaven-plugins repository. Custom themes walks through the same setup for a theme plugin.

Complete examples

The best way to learn JS plugin development is to study existing plugins. The deephaven-plugins repository contains production-ready examples:

Each plugin demonstrates:

  • Python registration with create_js_plugin from deephaven-plugin-utilities, which creates a JsPlugin.
  • React component structure.
  • Data flow between Python and JavaScript.
  • Build configuration with Vite.

To start from a template instead, see Quick start with cookiecutter.