react-msaview (JBrowseMSA)
An interactive multiple sequence alignment viewer.
- In: an alignment (FASTA, Stockholm, Clustal, A3M or EMF), optionally with
a Newick tree and GFF3 domains
- Out: a zoomable view of the tree beside the alignment, a shareable link,
or an SVG figure
Features
- Tree and alignment rendered together, tiled to stay fast on large inputs
- Protein domain overlays from GFF3, such as InterProScan output (generate them
with the CLI)
- Protein and nucleotide color schemes, including per-column dynamic schemes
- Conservation, property-conservation and sequence-logo tracks over the columns
- React component, UMD-in-HTML, and R htmlwidget entry points
- Shareable view state and SVG export
Documentation
Jump to what you need:
| You want to… | Start here |
|---|
| Use the viewer: load data, explore, export an image | User guide · live app · docs site |
| Build the files to open: sequences to alignment, tree, annotations | Tutorials · live |
| Embed the React component in your own app | Usage & embedding guide · live code examples · model API reference |
| Use it from R (ape, Biostrings, ggtree, Shiny, ggplot2) | ggmsaview, in its own repo |
| Annotate protein domains or exons, or render a figure headlessly | CLI README: interpro, interproscan, genestructure, export-svg |
| Contribute / hack on the code | Development |
Quick start (React)
import { MSAViewer } from 'react-msaview'
export default function App() {
// backticks (template literal) so the \n become real newlines
return (
<MSAViewer
msa={`>human\nMKAANSE\n>mouse\nMKA-NSE`}
tree="(human:0.1,mouse:0.2);"
colorScheme="clustal"
/>
)
}
USAGE.md has the install line,
every prop, the model API and the UMD bundle. The
live examples have runnable snippets.
Quick start (R)
remotes::install_github("GMOD/ggmsaview")
library(ggmsaview)
msaview(msa = "alignment.fasta", tree = "tree.nwk", color_scheme = "clustal")
ggmsaview also draws the viewer as a
ggplot2 figure, and its README covers ape, Biostrings, ggtree, treeio and Shiny.
Protein domains
The viewer draws domain annotations, such as the GFF the CLI
writes, as labelled boxes on the alignment:
Packages
Development
git clone https://github.com/GMOD/JBrowseMSA
cd JBrowseMSA
pnpm install
| Command | What it does |
|---|
pnpm dev | Run the demo app with hot reload (edits in packages/lib/src/) |
pnpm build | Build all packages |
pnpm test | Run the test suite |
pnpm figures | Regenerate the README figures (headless SVG, packages/lib/scripts) |
pnpm screenshots | Regenerate the user-guide app screenshots (diff-gated; only changed images rewrite) |
pnpm lint / format / typecheck | Lint (oxlint), format (oxfmt, plus Prettier for .astro), typecheck all packages |
The workspace is pnpm-only. pnpm-lock.yaml at the root is the single
lockfile, and a preinstall guard
(scripts/only-pnpm.mjs) stops an accidental
npm install or yarn from producing a second, unvetted dependency tree. Get
pnpm with corepack enable.
CLAUDE.md has the architecture notes; the core state model is
packages/lib/src/model.ts (MobX-state-tree), and observer-wrapped components
re-render when observed model properties change.
Deployment
- Docs site → gmod.org/JBrowseMSA, with the demo app at
gmod.org/JBrowseMSA/demo.
pnpm build:pages builds both into pages-dist/
(docs at the root, app under /demo); the
Deploy docs site workflow deploys it via
GitHub's native Pages action on every push to main. Trigger it by hand with
workflow_dispatch for an out-of-band deploy.
- Examples gallery → gmod.org/JBrowseMSA/examples: the docs site's examples
page renders
packages/examples, so the same push deploys it. The package has
no standalone site; jbrowse.org/storybook/msa no longer hosts a copy.
Releasing
Run scripts/release.js to create and push a new git tag. We use npm trusted
publishing, so pushing a tag to GitHub launches the npm release automatically.
scripts/release.js also writes the release's CHANGELOG section
from its commits, with git-cliff and the groups in
cliff.toml. We automated the changelog after the hand-written one
stopped at v3.1.3 while the packages reached 6.5.0.
Related projects
Builds on abrowse and
phylo-react.
