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:
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.jsonand the Vite configuration file are at its top, and the source is insrc/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.tsand a separate plugin file. The element example on this page defines the plugin directly insrc/js/src/index.tsx. The widget andMultiPluginexamples use separate plugin files, as the templates do. - The templates name the Vite configuration file
vite.config.js. This page usesvite.config.ts. - The templates put the registration class in
register.py, declare the entry point insetup.cfg, and copy the built JS into the package's_jsdirectory. This page puts the registration class insrc/my_plugin/__init__.py, declares the entry point inpyproject.toml, and copies the built JS intosrc/my_plugin/js. - The templates create the plugin with
create_js_pluginfromdeephaven-plugin-utilities. This page subclassesJsPluginso 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 thePluginTypevalues from the@deephaven/pluginpackage. 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 thepackage.jsonname, unless it sets a different one, as aJsPluginsubclass can. Set both to the package name. - A plugin inside a
MultiPluginis registered under its ownname.
For the full set of properties each type accepts, see PluginTypes.ts in the web-client-ui repository.
| Type | Purpose |
|---|---|
PluginType.ELEMENT_PLUGIN | Maps custom element names to React components for deephaven.ui. |
PluginType.WIDGET_PLUGIN | Renders a server-side object in a panel. The supportedTypes property lists the server object types the plugin handles, and component renders them. |
PluginType.DASHBOARD_PLUGIN | Mounts a component once per dashboard. Use it to register custom panel types or respond to dashboard events. |
PluginType.TABLE_PLUGIN | Adds 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_PLUGIN | Provides one or more custom themes. See Custom themes. |
PluginType.AUTH_PLUGIN | Adds a login method to the web UI. |
PluginType.MIDDLEWARE_PLUGIN | Wraps 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_PLUGIN | Bundles 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, oricon.
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
pluginsarray a unique, non-emptyname. A common convention is to append a suffix to the package name, such as@my-org/my-plugin.DashboardPlugin. - Make every entry in the
pluginsarray an object. - Don't nest a
MultiPlugininside anotherMultiPlugin. - Keep the server registration unchanged. The Python registration still points to a single
mainfile, and theMultiPluginis 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
typeor an emptynameand 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
nullor 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:
- JavaScript bundle: Contains the React components and any other client-side code.
- 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-pluginhelps 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, andreact-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.jsonand the files listed in itsfilesfield. - If
src/js/dist/doesn't exist yet,package_jscopies 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 theloaderfield's"package"value to its package name. - In your plugin's
package.json, list that name in theloaderfield'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.shcopies the field frompackage.jsonintomanifest.json. - Python package with
create_js_plugin:deephaven-plugin-utilities0.1.0 and later read the field frompackage.json. - Python package with a
JsPluginsubclass: Add aloaderproperty that returns the same value, for examplereturn {"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:
- Package the plugin with the
pack-plugins.shscript from theweb-plugin-packagerDocker image, as shown in Configure JS plugins. The script extracts each npm package and writes amanifest.jsonfile that lists them. If the plugin isn't published to npm:- Build the plugin.
- Copy its npm package directory into the packager stage, for example
COPY src/js /my-plugin. - 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 runsnpm packfrom a temporary subdirectory.
- Copy the contents of the generated
js-pluginsdirectory into thejs-plugins/subdirectory of the server's configuration directory, so thatmanifest.jsonis at<configDir>/js-plugins/manifest.json. Alternatively, set thedeephaven.jsPlugins.resourceBaseconfiguration property to the directory that containsmanifest.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:
- Build the JS:
npm install && npm run buildinsrc/js/. - Install the Python package:
pip install -e ./path/to/my-plugin. This runssetup.py, which copies the built bundle into the Python package. - Start the server. The server registers the plugin at startup, and the web UI loads it.
- Iterate. After each change:
- Edit the JS code and rebuild it.
- Reinstall the Python package so it picks up the new bundle.
- Restart the Deephaven server. The server registers JS plugins only at startup, so it keeps serving the old bundle until you restart it.
- 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:
- 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.registercall for the JS plugin from itsRegistrationclass. Server-side code includes thedeephaven.uicomponent from theelementtemplate and the object type from thewidgettemplate. - If you registered it through a server manifest, remove its entry from
manifest.json.
- In the configuration file or as a JVM argument, set a
deephaven.jsPlugins.<name>configuration property to the npm package directory, such asdeephaven.jsPlugins.my-plugin=/path/to/my-plugin/src/js.<name>can be any label that doesn't contain a..- Don't use
resourceBaseas the label, becausedeephaven.jsPlugins.resourceBasesets the server manifest directory.
- 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:
- Clone the deephaven-plugins repository and put your plugin in its
plugins/directory. - Run the plugin development server from that clone. It rebuilds the plugins in
plugins/whenever you save a change, and serves them. - 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:
plotly-express: Plotly visualization integration. Uses aMultiPluginto register a widget plugin and a legacy dashboard plugin.matplotlib: Matplotlib figure support.ui: Thedeephaven.uiframework itself. Also uses aMultiPlugin.
Each plugin demonstrates:
- Python registration with
create_js_pluginfromdeephaven-plugin-utilities, which creates aJsPlugin. - React component structure.
- Data flow between Python and JavaScript.
- Build configuration with Vite.
To start from a template instead, see Quick start with cookiecutter.