Plugins

In jbrowse-web and jbrowse-desktop, the top-level plugins array says what to load. A published plugin is named by its plugin-store entry; a plugin you host yourself is named by its url.

{
  "plugins": [
    { "storePlugin": "MsaView" },
    {
      "name": "MyPlugin",
      "url": "https://example.com/plugins/myplugin.umd.js"
    },
    {
      "name": "MyLocalPlugin",
      "umdLoc": { "uri": "myplugin.umd.js" }
    }
  ]
}

• storePlugin is the name the plugin store lists it under. JBrowse resolves it against the store when the config loads, picking a build published for the version of JBrowse doing the reading and checking its integrity hash. Nothing in the config pins a url or a version, which is what makes it the form to use in a config that will be read for years — a permanent url, a track hub. Plugin authors submit a PR to jbrowse-plugin-list to be listed.
• name must match the plugin's own registration (name = 'MyPlugin' in the plugin class) for a UMD build, which is looked up by that name once its script has run. An ESM build has its own, and a store entry supplies one.
• Embedded components load plugins inline; see the inline plugins example.

Naming a build directly#

url is the simplest field and equals umdUrl. The others differ in module format and in what the path resolves against:

umdLoc/esmLoc suit a plugin file that lives beside config.json. Both formats load on the main thread and in the RPC workers. An ESM build can split into chunks that load when first used, which a UMD build cannot; see What your plugin costs at load.

Add integrity beside a UMD url to have the browser check the bytes against the hash before running them; the store publishes one for each UMD build.

A url is an answer computed on the day the config was written. storePlugin defers it to load time instead, and the two can ride together — the ref for a JBrowse that resolves it, the url for one that does not, and as the fallback when the store cannot be reached:

{
  "plugins": [
    {
      "storePlugin": "MsaView",
      "name": "MsaView",
      "url": "https://jbrowse.org/plugins/jbrowse-plugin-msaview/3.10.0/dist/jbrowse-plugin-msaview.umd.production.min.js"
    }
  ]
}

The retired cjsUrl#

The cjsUrl field is gone as of v5. It loaded a plugin by writing it to a temp file and requireing it in jbrowse-desktop's renderer, which nothing needed: Electron's renderer runs both other formats, and a plugin reaching the main process does it through window.require('electron') whichever format it ships in. A config still naming one fails that plugin by name and opens without it.

✕

Open in JBrowse Web ↗Open in JBrowse Desktop ↗

Or rebuild it from your own data:

Desktop

Opening in Desktop needs JBrowse Desktop 5.0+, and saves the view as a reopenable session.

Nothing happens?

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

Copy

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

With your own data, the steps behind the figure:

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.

Web

Its genome and tracks are hosted, so File → Open track... there adds your own files beside them.

With your own data, the steps behind the figure:

1. Put your genome in your JBrowse Web's config.json: jbrowse add-assembly adds it.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.

Spec

This session spec draws the figure from test_data/volvox/config.json: paste it after &session=spec- on a JBrowse Web link that loads that config.

Copy

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

Notebook

The same view with jbrowse-anywidget, from the config the figure loads. Swap a track's uri for your own file.

Copy

from jbrowse_anywidget import JBrowseApp, fetch_hub

config = fetch_hub("https://jbrowse.org/code/jb2/main/test_data/volvox/config.json")
app = JBrowseApp(
    assemblies=config["assemblies"],
    tracks=config.get("tracks", []),
    views=[
        {
            "type": "LinearGenomeView",
            "assembly": "volvox",
            "loc": "ctgA:1-20000"
        }
    ],
)
app  # display the widget

Image

jbrowse-img draws the same view as an SVG, from the command line and without a browser. Point --config at your own config, or swap a track for your own file with --bam, --vcfgz and the other file flags.

Copy

npx @jbrowse/img --config https://jbrowse.org/code/jb2/main/test_data/volvox/config.json \
  --assembly volvox --loc ctgA:1-20000 \
  --width 1500 --out figure.svg

--out figure.png writes a PNG instead, through rsvg-convert (apt install librsvg2-bin, brew install librsvg).

Agent

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.

Copy

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 \
  --width 1500 --height 800 \
  --spec session.json -o figure.png

The figure was taken after clicks this command does not make, so its picture can differ.

It leaves out 3 callouts anchored to what the clicks bring up.

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 also#

• Plugin store
• Developer guide
• No-build plugin
• Simple plugin tutorial