Skip to main content

Plugins

TL;DR: in jbrowse-web and jbrowse-desktop, add a plugin by listing its name (which must match the name the plugin registers itself under) and bundle url in the top-level plugins array.

Embedded components load plugins inline; see the inline plugins example.

{
  "plugins": [
    {
      "name": "GDC",
      "url": "https://unpkg.com/jbrowse-plugin-gdc/dist/jbrowse-plugin-gdc.umd.production.min.js"
    }
  ]
}

The name must match the name the plugin registers itself under in its source (e.g. name = 'GDC' in the plugin class), or the plugin fails to load. The url (or one of the location fields below) points at the built plugin bundle. The plugin store lists unpkg URLs for published plugins, which you can also download to your own server.

url is the simplest option and is equivalent to umdUrl. Other fields cover different situations:

FieldModule formatPath resolved relative to
urlUMDindex.html
umdUrlUMDindex.html
umdLocUMDconfig.json
esmUrlESMindex.html
esmLocESMconfig.json
cjsUrlCJSindex.html (desktop only)

Which one to reach for:

  • umdLoc or esmLoc when your plugin file lives alongside your config.json
  • esmUrl/esmLoc for a pure ESM module
  • cjsUrl for jbrowse-desktop, since Electron does not support ESM and the jbrowse-plugin-template outputs CJS-specific code for desktop

umdLoc example

{
  "plugins": [
    {
      "name": "MyPlugin",
      "umdLoc": { "uri": "plugin.js" }
    }
  ]
}

esmUrl example

{
  "plugins": [
    {
      "name": "MyPlugin",
      "esmUrl": "https://unpkg.com/my-plugin/dist/index.mjs"
    }
  ]
}

Plugin store

Plugin authors can submit their plugin via PR to jbrowse-plugin-list.

You can verify the plugin is installed properly by checking the Plugin Store:

Opening the plugin store from the Tools menu. Plugins installed via the config (here UMDUrlPlugin) show a lock icon in the Installed plugins section, indicating they cannot be removed through the GUI. The Available plugins list below offers one-click installs. Open this view in JBrowse ↗

The steps behind the figure above, run against your own data.

  1. Open your genome: on the JBrowse Desktop start screen click Open new genome (or Show all available genomes to pick a hosted one).This figure uses volvox, loaded from a .2bit genome.
  2. Type your region of interest into the location box and press Enter.This figure is at ctgA:1-20000.

Open this view in JBrowse Desktop ↗

Opens JBrowse Desktop (JBrowse Desktop 5.0+) at this view and saves it as a reopenable session — swap in your own files afterwards.

Nothing happens? Paste this link into Desktop's Open JBrowse Web link... (start screen, or File → Session):

https://jbrowse.org/code/jb2/main/?config=test_data%2Fvolvox%2Fconfig.json&session=spec-%7B%22views%22%3A%5B%7B%22type%22%3A%22LinearGenomeView%22%2C%22assembly%22%3A%22volvox%22%2C%22loc%22%3A%22ctgA%3A1-20000%22%7D%5D%7D&sessionName=JBrowse+docs%3A+plugin_store

This session spec pastes after &session=spec- on any JBrowse Web instance.

{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-20000"
    }
  ]
}

Loaded against config: test_data/volvox/config.json

The same view with jbrowse-anywidget. Point the adapter at your own file.

from jbrowse_anywidget import LinearGenomeView, make_assembly

view = LinearGenomeView(
    assembly=make_assembly("volvox", "https://your-server/your-genome.fa.gz"),
    location="ctgA:1-20000",
)

view  # display the widget

Hand this to a coding agent. It rebuilds the figure above headlessly, and the session file is then the thing to edit — swap an adapter uri for your own file and rerun.

cat > session.json <<'JSON'
{
  "views": [
    {
      "type": "LinearGenomeView",
      "assembly": "volvox",
      "loc": "ctgA:1-20000"
    }
  ]
}
JSON

npx @jbrowse/capture --instance https://jbrowse.org/code/jb2/main/ \
  --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --session session.json -o figure.png

Using JBrowse with AI agents covers the rest: hosted genomes to point it at, and why waiting for the render is the part that goes wrong.

See our developer guide for developing plugins, or the plugins page for published plugins.

See also