# Mol*: the web macromolecular viewer that became a viewer platform

> Mol* grew out of two older viewers, LiteMol from PDBe and NGL from RCSB PDB, and is now the rendering layer behind PDBe, AlphaFold DB and RCSB PDB. Its current development is a v6 prototype that restructures the codebase into pnpm workspace packages, which is a migration story as much as a feature story.

**molstar/molstar** — A comprehensive macromolecular library

- Repository: https://github.com/molstar/molstar
- Website: https://molstar.org
- Stars: 1,041 · Forks: 263
- Language: TypeScript
- License: MIT
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/molstar-molstar

## Two older viewers, merged into one

The stated goal of Mol* is to provide a technology stack that serves as a basis for the next-generation data delivery and analysis tools for macromolecular structure data, and not only for that.

The origin explains the shape of the project. Mol* development was jointly initiated by PDBe and RCSB PDB to combine and build on the strengths of LiteMol, developed by PDBe, and NGL, developed by RCSB PDB. So this is a consolidation of two institutional codebases, and the technical decisions you see in it are the residue of reconciling two different approaches to the same problem.

The scale it handles is the other thing to understand. The description calls it a comprehensive macromolecular library, and the paper it asks you to cite describes it as a modern web app for 3D visualization and analysis of large biomolecular structures, in Nucleic Acids Research, 2021. Large is the operative word. A protein is a few thousand atoms and a ribosome is hundreds of thousands, and a browser that renders them at interactive rates has to think about buffer sizes, picking precision and level of detail, which is a different problem from rendering a molecule with fifty atoms.

The topics list names the technologies underneath: webgl, webgl2, webxr, global-illumination, immersive-ar, virtual-reality, web-graphics, molecular-graphics and scientific-visualization. WebXR and immersive AR in that list are not incidental, they are how structural biology started to be taught with headsets and handheld devices rather than on a projector.

The project also documents its own ancestry in a previous work section: LiteMol Suite, WebChemistry, NGL Viewer, MMTF, MolQL and the PDB Component Library, among others.

## The two deployments that define what a plugin has to do

The integrations section is the best evidence for how Mol* is actually used, and it names two separate plugin packages with different jobs.

pdbe-molstar is the Mol* implementation used by EMBL-EBI data resources such as PDBe, PDBe-KB and AlphaFold DB. It can be used as a JS plugin and as a Web component, and it supports property and attribute based easy customisation. It provides helper methods to facilitate programmatic interactions between the web application and the 3D viewer, and it provides a superposition view for overlaying all the observed ligand molecules on representative protein conformations.

That last feature is a good illustration of the kind of problem this library exists for. Ligands are small molecules bound to a protein, and the question a structural biologist often wants answered is whether the ligand sits in the same place across many structures of the same protein. That is a comparison across models, not a rendering of one model, and it is the kind of question a general purpose 3D library does not answer.

rcsb-molstar is the plugin used by RCSB PDB. It provides additional presets for the visualization of structure alignments and structure motifs such as ligand binding sites, and it allows interactively adding or hiding parts of chains, as seen in the 3D Protein Feature View.

So the pattern is a core viewer plus a per-institution plugin, and that is the design that makes the project extensible. The shared core handles the structures, the representation and the rendering, and each site adds its own presets, its own UI conventions and its own domain features on top. It is also why the customisation surface is described in terms of properties and attributes, since a Web component has to be configurable from outside the JavaScript that instantiates it.

## The v6 prototype splits one library into a workspace of packages

The project structure section describes a v6 prototype that separates code into pnpm workspace packages, and the layout is worth reading carefully because it changes what you depend on.

The shared library layers live in packages/{core,io,model,graphics}. The plugin runtime, the React UI and Node capture live in packages/plugin/{core,ui,headless}. Standalone MVS construction is separated from plugin loading in packages/mvs/{builder,runtime}. Then extensions/, apps/, examples/, servers/ and cli/ own their dependencies and builds, distributions/molstar/ assembles the classic and browser ESM distribution, and smoke/ checks isolated package consumers and browser rendering.

Two entries deserve attention. The headless plugin package is the one that makes Node capture possible, meaning you can run Mol* outside a browser, which is what the image-renderer and the MVS stories examples need. And the separation of MVS construction from plugin loading in packages/mvs is a design decision about what is a data format and what is a UI, which matters if you want to generate Molecular Scene descriptions without shipping the whole viewer.

The tooling around the packages is where the discipline shows. The check:workspace script runs a chain of five separate checks, on the workspace itself, on a slim bundle, on a registry comparison, on a composition check and on a query language check. There is a separate version:check that verifies versions are synchronised, and a version:sync that writes them. The smoke/ directory exists to check isolated package consumers and browser rendering, and the smoke browser requires Chromium.

The repository root also has breaking-v6-changes.md and a V6.md, plus a .v6/ directory holding the workspace guide and the implementation plan. That is a project in the middle of a structural change, and the presence of the change log is a signal that the API surface is not settled.

## Building with pnpm, and the four commands you actually need

Building requires Node 22.13 or newer and the pnpm version specified in package.json, and the engines field in the package manifest asks for node >=22.13.0.

The dev and build commands are short and selective, which is the useful part.

```bash
pnpm install
pnpm build
pnpm dev                            # all apps and browser examples
pnpm dev:apps                       # all apps
pnpm dev:apps -- viewer             # selected app
pnpm dev:examples                  # all browser examples
pnpm dev:examples -- basic-wrapper  # selected example
```

The comment after each command tells you what it does, and the ability to select a single app or a single example is what makes the tree usable during development. With sixteen example directories in the repository, from alpha-orbitals to volume-tools, building everything on every change is not practical.

The build script itself is three stages, and the split matters. build:lib runs the workspace version script, then the TypeScript project build, then the assets script. build:apps runs the esbuild app script for all apps in production mode. build:distribution runs the distribution script, which produces the classic and browser ESM distribution under distributions/molstar/.

For verification, the README names three commands: pnpm check:workspace to check package boundaries, pnpm test and pnpm --dir smoke smoke to check existing behavior and packed ESM consumers. Native GL is opt-in, with pnpm native:install installing it separately and pnpm test:native running the native tests, and for capture you use pnpm native:run with the smoke headless command. A clean rebuild is node scripts/clean.js --all, and there are separate clean:build and clean:lib targets, so you can clean one layer without discarding the other.

## Code generators live under the package that owns them

One detail in the README says more about the project's engineering culture than any amount of feature description: code generators are compiled under their owning cli/<name>/lib/ directories.

The examples given are concrete.

```bash
node cli/cifschema/lib/index.js -mip @molstar/core/data -o packages/io/src/reader/cif/schema/mmcif.ts -p mmCIF
node cli/lipid-params/lib/index.js -o packages/model/src/model/structure/model/types/lipids.ts
node cli/syminfo/lib/index.js
node cli/cif2bcif/lib/index.js input.cif output.bcif
```

Each generator writes into a specific package, and the command lines take the target as an argument, which means the generated code is committed and the generator is reproducible. The cifschema generator writes the mmCIF schema into packages/io/src/reader/cif/schema/mmcif.ts with the relevant core data as an input, the lipid-params generator writes the lipid type definitions into the structure model, and cif2bcif converts a .cif file into a binary .bcif.

That last one is a performance decision, and it is the kind of thing that distinguishes a library used in production from a demo. A structure file that arrives over the network as text has to be parsed, and parsing is the bottleneck. Generating a schema and a binary format lets the parse happen once at build time and the data be shipped in a form that loads fast.

The symmetry with the workspace layout is the point. The generators are not in a top level tools directory; each one sits next to the package whose types it maintains, so the ownership boundary the package layout draws is also the boundary for code generation. There is a cli/ directory at the repository root, and a scripts/ directory beside it for the build and deploy tooling.

## What Mol* is the wrong choice for

Three cases, and the first is the one that catches people.

The first is a production application that needs a stable dependency. Mol* is at v5.13.0 with a v6 prototype restructuring the codebase into workspace packages, and the repository carries a file specifically for breaking v6 changes. If your application pins a Mol* version, you are pinning into a codebase that is mid-migration, and when the v6 packages land your imports may change shape. For a research group iterating on the viewer that is fine, and for a product with a release cadence it is a scheduling problem.

The second is a viewer that has to be extremely small. The package has a slim-bundle check in the workspace tooling, so bundle size is a concern the project tracks, but this is a comprehensive macromolecular library with a React UI layer, a plugin runtime and a headless mode. A site that needs a small inline molecule widget is served better by the pdbe-molstar Web component path or by a purpose built viewer for a single format.

The third is anything that is not a web application. There is native GL support, but it is opt-in and installed separately with pnpm native:install, and the headless package is for Node capture rather than for a desktop application. This is a browser technology.

The alternative worth naming is the pair of projects Mol* was built from, LiteMol and NGL, and the general category of a smaller single purpose viewer. LiteMol and NGL are not competitors today so much as the components that were merged. The reason to choose Mol* over a general purpose 3D library is domain knowledge: it knows what a residue, a chain, a ligand binding site and a structure alignment are, and it ships the domain specific presets that a generic WebGL scene graph would leave you to build.

## Conclusion

Mol* fits a research group that needs to show large structures in a browser, from a few thousand atoms to a whole ribosome, with a UI layer they can extend, and it fits a data provider that needs a viewer rather than a link to a third party site. It does not fit a team that wants a stable, versioned API today, because the v6 workspace restructure is in progress and the repository carries a breaking-v6-changes.md file, so the shape of the packages you depend on is moving. Check three things before you commit. Check whether the classic distribution or the v6 workspace packages are the right target for you, because the README describes the v6 prototype layout with packages/{core,io,model,graphics} and the classic and browser ESM distribution under distributions/molstar. Check the browser ESM entry points under build/esm/ and the served build/viewer/ and build/mvs-stories/ output, since that is what you actually deploy. And check the Node engine requirement, which is 22.13 or newer, with pnpm as the package manager. The last push was on 2026-10-19, the newest release listed is v5.13.0 from 2026-10-04, and the license is MIT.

## FAQ

### What is Mol* and who builds on it?

Mol* is a technology stack for data delivery and analysis tools for macromolecular structure data, jointly initiated by PDBe and RCSB PDB by combining LiteMol and NGL. The pdbe-molstar plugin powers PDBe, PDBe-KB and AlphaFold DB, and rcsb-molstar powers RCSB PDB.

### What are the requirements for building Mol*?

Node 22.13 or newer and the pnpm version specified in package.json, with the engines field requiring node >=22.13.0. The commands are pnpm install, pnpm build and pnpm dev, with variants to run a single app or a single example.

### What is the v6 prototype in the Mol* repository?

It separates the code into pnpm workspace packages, with packages/{core,io,model,graphics} owning the shared library layers, packages/plugin/{core,ui,headless} owning plugin runtime, React UI and Node capture, and packages/mvs/{builder,runtime} separating standalone MVS construction from plugin loading. The repository includes breaking-v6-changes.md.

### How do you verify a Mol* build?

Run pnpm check:workspace to check package boundaries, pnpm test for existing behavior and pnpm --dir smoke smoke for packed ESM consumers, where the smoke browser requires Chromium. Native GL is opt-in via pnpm native:install with pnpm test:native, and node scripts/clean.js --all gives a clean rebuild.

### What license is Mol* released under?

MIT, with a LICENSE file at the root of the repository. The newest listed release is v5.13.0 from 2026-10-04, and the last push was on 2026-10-19.

## Sources

- [License: MIT](https://github.com/molstar/molstar/blob/master/LICENSE)
- [molstar/molstar on GitHub](https://github.com/molstar/molstar)
- [Project website](https://molstar.org)
- [README](https://github.com/molstar/molstar/blob/master/README.md)
- [Releases](https://github.com/molstar/molstar/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/molstar-molstar