Skip to main content

Writing a plugin

TL;DR: Clone an official template, follow its README, and copy from its worked example. Templates ship a working build and a local JBrowse instance to test against.

Plugins add new pluggable elements (views, tracks, displays, adapters, widgets, etc.) and can modify application behavior by watching state. See pluggable elements for the full list of element types you can register.

Official templates

TemplateBundler
jbrowse-plugin-esbuild-templateesbuild
jbrowse-plugin-templaterollup

They are otherwise the same: pnpm, vitest unit tests, and Puppeteer end-to-end tests against a nightly JBrowse build. Pick esbuild for faster builds; rollup is older and more widely referenced in existing examples.

Both ship a custom view (src/HelloView) as their worked example. For a custom track/display, scaffold from a template and then follow Plotting features in a custom display. Its complete plugin lives in example-plugins/score-example/, and every code block in that guide is generated from that source.

What's in a plugin

A plugin is a class extending Plugin. name is the only required member; the rest you implement as needed:

  • install() — registers pluggable elements against the pluginManager.
  • configure() — runs afterwards, typically to set up mobx autoruns over application state.
  • version — what the plugin store shows beside the name.
  • uninstall() — a hook nothing in JBrowse calls; don't put teardown in it.

The element-specific guides walk through each type:

  • Custom track and display types — Define track types (high-level identity) and display types (how a track renders in a given view)
  • Plotting features in a custom display — Build a plugin that fetches features in a worker and plots them on the main thread with Canvas2D, no shaders required
  • GPU displays — Build a display that renders with WebGPU/WebGL2 and falls back to Canvas2D
  • Add-track workflows — Custom UI in the Add track dialog for non-standard track types
  • Custom adapters — Read data from custom file formats with feature, regions, or sequence adapters
  • Custom connections — Add many tracks at once, or dynamically query a remote resource, with a connection type
  • Custom view types — Add entirely new view panels such as DotplotView or CircularView
  • Custom widgets — Add new drawer/panel UI components
  • Drawer widgets — Launching sidebar or popup widgets in the embedded LGV
  • Menus — Add items to the application menu bar, the track menu, and track context menus
  • SVG export — How to implement renderSvg on a custom display type
  • Text search adapters — Implement a custom backend for the search box
  • Upgrading to v5 — What changed for plugin authors and embedders in JBrowse 2 v5.0.0

A plugin can also add its own configuration slots, through one of three class members that differ only in where the slots land:

  • configurationSchema nests them under the plugin's own name, so a slot reads as configuration.MyPlugin.mySlot. This is the one to reach for: the slots live in the plugin's own namespace.
  • configurationSchemaUnnamespaced merges them into configuration directly.
  • rootConfigurationSchema is a function of the plugin manager whose result is spread into the root config, for a schema that has to be built against what is registered.

For plugins that don't need a build step (e.g. jexl callbacks or small behavior tweaks), see writing a no-build plugin.

See also