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

Package	Description
packages/lib	Main react-msaview React component
website	Docs site (deployed at gmod.org/JBrowseMSA)
packages/app	Demo application (deployed at gmod.org/JBrowseMSA/demo)
packages/examples	Live usage examples (deployed at gmod.org/JBrowseMSA/examples)
packages/cli	Domain/exon GFFs and headless SVG export
packages/msa-parsers	MSA file format parsers
packages/svgcanvas	SVG canvas rendering (ESM fork of svgcanvas)

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

• jbrowse-plugin-msaview: a JBrowse 2 plugin for viewing MSAs, supported by this repo
• ProteinBrowser: a suite of protein analysis tools built on this viewer

Builds on abrowse and phylo-react.