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

```json
{
  "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](https://jbrowse.org/jb2/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](https://github.com/GMOD/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](https://jbrowse.org/storybook/lgv/inline-plugin/).

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

| Field    | Module format | Path resolved relative to |
| -------- | ------------- | ------------------------- |
| `url`    | UMD           | index.html                |
| `umdUrl` | UMD           | index.html                |
| `umdLoc` | UMD           | config.json               |
| `esmUrl` | ESM           | index.html                |
| `esmLoc` | ESM           | config.json               |

`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
[](https://jbrowse.org/jb2/docs/developer_guides/plugin_load_cost).

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:

```json
{
  "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 `require`ing 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.

<Figure src="/img/plugin_store.png" caption="Opening the plugin store from the Tools menu. Plugins installed via the config (here UMDUrlPlugin) show a lock icon in the Installed plugins section, and the GUI cannot remove them. The Available plugins list below offers one-click installs."/>

## See also

- [](https://jbrowse.org/jb2/docs/user_guides/plugin_store)
- [](https://jbrowse.org/jb2/docs/developer_guide/)
- [No-build plugin](https://jbrowse.org/jb2/docs/developer_guides/no_build_plugin)
- [Simple plugin tutorial](https://jbrowse.org/jb2/docs/developer_guides/simple_plugin)