Skip to main content

Writing a plugin

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.

The two templates 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 declares what it draws as a mark list, which every backend and the SVG export draw
  • GPU displays — Write a shape of your own when no shared one fits, and declare it as a mark the WebGPU, WebGL2 and Canvas2D backends all draw
  • 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
  • What your plugin costs at load — A config that names your plugin downloads and evaluates all of it before anything draws — how to make that cost your registration rather than your whole bundle

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