Skip to content

Example: API Diagnostics

typekey/plugin-example

A reference plugin that exercises every public host API. It's the canonical starting point for plugin authors — clone it, build it, and use it to verify your host wiring is correct before writing a real plugin.

What it shows

  • State Inspector — live JSON of species, selectedRegion, selectedRNA, channels, favorites, history, highlightRegions.
  • Navigation tester — host.navigate({ chr, start, end }) and host.navigate({ transcriptId }).
  • Highlight tester — host.highlight.add / remove / clear.
  • Storage tester — namespaced host.storage.get / set / remove / keys / clear.
  • Host info — host.info (pluginId, version, apiVersion, permissions).

Because it touches everything, its manifest requests all four permissions:

{
  "id": "plugin-example-diagnostics",
  "name": "API Diagnostics",
  "version": "0.1.0",
  "apiVersion": "1",
  "minHostVersion": "0.0.1",
  "entry": "./plugins/plugin-example-diagnostics/index.js",
  "permissions": ["state:read", "navigation:write", "highlight:write", "storage:write"],
  "panel": { "position": "right", "title": "API Diagnostics" },
  "author": "RBrowser Core",
  "description": "Exercises every public host API. Use to verify the plugin SDK contract."
}

Entry point

The default export is a PluginModule that mounts a React app and tears it down on unload:

import * as ReactDOM from 'react-dom/client'
import { definePlugin } from '@rbrowser/plugin-sdk'
import { RBrowserHostProvider, RBrowserState, useRBrowserHost } from '@rbrowser/plugin-sdk/hooks'

let root: ReactDOM.Root | null = null

export default definePlugin({
  activate(host) {
    console.log('[plugin-example] activate', host.info)
  },
  render(container, host) {
    if (root) root.unmount()
    root = ReactDOM.createRoot(container)
    root.render(<App host={host} />)
  },
  deactivate() {
    if (root) { root.unmount(); root = null }
  }
})

Inside <App>, state is read with the namespaced hooks (e.g. RBrowserState.selectedRNA()) and actions go through useRBrowserHost().

Build

This plugin is built with @rbrowser/plugin-sdk and its companion CLI.

# 1. install deps (React, @rbrowser/plugin-sdk)
npm install

# 2. build the ESM bundle  →  dist/index.js (~150 KB)
npm run build

# 3. pack into a single .rbp  →  dist/plugin-example-diagnostics-<version>.rbp
npm run pack

npm run pack runs vite build then invokes the SDK CLI (rbrowser-plugin pack), which reads manifest.json + dist/index.js and writes the .rbp archive. See Packaging & CLI for details.

Install

  1. Drag the prebuilt plugin-example-diagnostics-<version>.rbp into the RBrowser Plugin Store panel — or use Plugin Store → ⚙ → Install from local file… and pick the .rbp.
  2. Toggle to Enabled; the panel mounts on the right side.

Author a new plugin

  1. Add @rbrowser/plugin-sdk as a dependency.
  2. export default definePlugin({ activate?, render, deactivate? }).
  3. npm run pack to produce a .rbp, then drag-install it via the Plugin Store.

Your plugin receives a host: RBrowserHost from the loader — never construct your own. See the Host Bridge for the full API.