Template to quickly start a new JBrowse plugin
You can use this template to create a new GitHub repository or a new local project.
- git
- Node.js (version 10 or greater)
- yarn (or npm which comes with Node.js)
- JBrowse 2 (version 2.0 or greater)
You can click the "Use this template" button in the repository (instructions here):
Or you can use the GitHub CLI:
$ gh repo create jbrowse-plugin-my-project --template https://github.com/GMOD/jbrowse-plugin-template.git
Or you can start a plugin locally:
$ git clone https://github.com/GMOD/jbrowse-plugin-template.git jbrowse-plugin-my-project
$ cd jbrowse-plugin-my-project
$ rm -rf .git
$ # If you want to use Git, re-initialize it
$ git init
Run yarn init
(or npm init
) and answer the prompts to fill out the
information for your plugin
- Make sure you at least enter a "name" (probably starting with "jbrowse-plugin-", or "@myscope/jbrowse-plugin-" if you're going to publish to an NPM organization)
- Other fields may be left blank
- leave the "entry point" as
dist/index.js
Now run yarn
(or rm yarn.lock && npm install
to use npm instead of yarn) to
install the necessary dependencies.
After this, run yarn setup
(or npm run setup
). This configures your project,
and adds a build of JBrowse 2 that can be used to test your plugin during
development.
$ yarn build ## or `npm run build`
To develop against JBrowse Web:
- Start a development version of JBrowse Web (see here)
- In this project, run
yarn start
(ornpm run start
) - Assuming JBrowse Web is being served on port 3000, navigate in your web browser to http://localhost:3000/?config=http://localhost:9000/jbrowse_config.json
- When you make changes to your plugin, it will automatically be re-built. You can then refresh JBrowse Web to see the changes.
Note: The current version of jbrowse-plugin-template
is only compatible
with "JBrowse 2" v2.0 or greater. If you are developing for a version of
"JBrowse 2" v1.x, please consider upgrading, or you will have to manually
downgrade the package dependencies in this template to ensure compatibility.
To test your plugin, there are several commands available:
Launches your local JBrowse 2 build that is used for integration testing, with
your plugin already included in the configuration. Your plugin must also be
running (yarn start
or npm run start
).
Runs any unit tests defined during plugin development.
Runs the cypress integration tests for your plugin.
Both the plugin and browse
must already be running.
Starts up the JBrowse 2 build as well as your plugin, and runs the cypress integration tests against them. Closes both resources after tests finish.
Launches the cypress test runner, which can be very
useful for writing integration tests for your plugin. Both the plugin and
browse
must already be running.
This template includes a Github action that runs your integration tests when you push new changes to your repository.
Once you have developed your plugin, you can publish it to NPM. Remember to
remove "private": true
from package.json
before doing so.
If you are using plugins in the embedded apps such as
@jbrowse/react-linear-genome-view
, then you can install jbrowse plugins such
as this one using normal "npm install jbrowse-plugin-yourplugin" if you have
published them to NPM, and use code like this
import React from 'react'
import ViewType from '@jbrowse/core/pluggableElementTypes/ViewType'
import PluginManager from '@jbrowse/core/PluginManager'
import Plugin from '@jbrowse/core/Plugin'
// in your code
import { createViewState, JBrowseLinearGenomeView } from '@jbrowse/react-linear-genome-view'
import MyPlugin from 'jbrowse-plugin-yourplugin'
export const MyApp = () => {
const state = createViewState({
assembly: {/*...your assembly config...*/},
plugins: [MyPlugin],
tracks: [/*...your track configs...*/],
location: 'ctgA:1105..1221',
})
return (
<JBrowseLinearGenomeView viewState={state} />
)
}
See https://jbrowse.org/storybook/lgv/main/?path=/docs/using-plugins--docs for live example, and also method for loading plugins from urls instead of from NPM in embedded
If you are using JBrowse Web, after the plugin is published to NPM, you can use unpkg to host plugin bundle. The plugin can then be referenced by URL in the config.json
A JBrowse Web config using this plugin would look like this:
{
"plugins": [
{
"name": "MyProject",
"url": "https://unpkg.com/jbrowse-plugin-my-project/dist/jbrowse-plugin-my-project.umd.production.min.js"
}
]
}
You can also use a specific version in unpkg, such as
https://unpkg.com/jbrowse-plugin-my-project@1.0.1/dist/jbrowse-plugin-my-project.umd.production.min.js
This template is set up in such a way that you can use both TypeScript and
JavaScript for development. If using only JavaScript, you can change
src/index.ts
to src/index.js
.
If using only TypeScript, you can remove "allowJs": true
from tsconfig.json
and "@babel/preset-react"
from .babelrc
(and from "devDependencies" in
package.json
).