Template to quickly start a new JBrowse plugin
You can use this template to create a new GitHub repository or a new local project.
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
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:
yarn start
(or npm run start
)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:
yarn browse
or npm run browse
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
).
yarn test
or npm test
Runs any unit tests defined during plugin development.
yarn cypress:run
or npm run cypress:run
Runs the cypress integration tests for your plugin.
Both the plugin and browse
must already be running.
yarn test:e2e
or npm run test:e2e
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.
yarn cypress
or npm run cypress
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
).