# molstar

> A comprehensive macromolecular library.

Latest version **5.11.0** (published 2026-07-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install molstar
pnpm add molstar
yarn add molstar
bun add molstar
```

Provides the commands `cif2bcif`, `cifschema`, `mvs-render`, `model-server`, `mvs-validate`, `volume-server`, `mvs-print-schema`, `model-server-query`, `volume-server-pack`, `volume-server-query`, `model-server-preprocess`.

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support; large bundle.

## Facts

| | |
|---|---|
| Version | 5.11.0 |
| Published | 2026-07-19 |
| First published | 2018-04-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=22.0.0 |
| Dependencies | 19 |
| Unpacked size | 76.6 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1010 |
| Author | Mol* Contributors |
| Maintainers | arose, dsehnal |

## Links

- npm: https://www.npmjs.com/package/molstar
- Repository: https://github.com/molstar/molstar
- Homepage: https://github.com/molstar/molstar#readme
- Issues: https://github.com/molstar/molstar/issues
- npm.io page: https://npm.io/package/molstar

## Dependencies (19)

- [cors](https://npm.io/package/cors.md) ^2.8.6
- [rxjs](https://npm.io/package/rxjs.md) ^7.8.2
- [io-ts](https://npm.io/package/io-ts.md) ^2.2.22
- [tslib](https://npm.io/package/tslib.md) ^2.8.1
- [express](https://npm.io/package/express.md) ^5.2.1
- [argparse](https://npm.io/package/argparse.md) ^2.0.1
- [mutative](https://npm.io/package/mutative.md) ^1.3.0
- [immutable](https://npm.io/package/immutable.md) ^5.1.9
- [remark-gfm](https://npm.io/package/remark-gfm.md) ^4.0.1
- [@types/node](https://npm.io/package/@types/node.md) ^22.20.1
- [compression](https://npm.io/package/compression.md) ^1.8.1
- [@types/express](https://npm.io/package/@types/express.md) ^5.0.6
- [react-markdown](https://npm.io/package/react-markdown.md) ^10.1.0
- [@types/argparse](https://npm.io/package/@types/argparse.md) ^2.0.17
- [swagger-ui-dist](https://npm.io/package/swagger-ui-dist.md) ^5.32.9
- [@types/benchmark](https://npm.io/package/@types/benchmark.md) ^2.1.5
- [h264-mp4-encoder](https://npm.io/package/h264-mp4-encoder.md) ^1.0.12
- [@types/compression](https://npm.io/package/@types/compression.md) 1.8.1
- [@types/swagger-ui-dist](https://npm.io/package/@types/swagger-ui-dist.md) 3.30.6

## Recent versions

- 5.11.0 (latest) — 2026-07-19
- 5.0.0-dev.13 (next) — 2025-09-03
- 5.10.1 — 2026-06-14
- 5.10.0 — 2026-06-14
- 5.9.0 — 2026-05-03
- 5.8.0 — 2026-04-03
- 5.7.0 — 2026-02-28
- 5.6.1 — 2026-01-23
- 5.6.0 — 2026-01-18
- 5.5.0 — 2025-12-22
- 5.4.2 — 2025-12-07
- 5.4.1 — 2025-11-16
- 5.4.0 — 2025-11-16
- 5.3.0 — 2025-11-05
- 5.2.0 — 2025-10-31
- … 312 more at https://npm.io/package/molstar/versions

## README

[![License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](./LICENSE)
[![npm version](https://badge.fury.io/js/molstar.svg)](https://www.npmjs.com/package/molstar)
[![Build](https://github.com/molstar/molstar/actions/workflows/node.yml/badge.svg)](https://github.com/molstar/molstar/actions/workflows/node.yml)
[![Gitter](https://badges.gitter.im/molstar/Lobby.svg)](https://gitter.im/molstar/Lobby)

# Mol*

The goal of **Mol\*** (*/'mol-star/*) is to provide a technology stack that serves as a basis for the next-generation data delivery and analysis tools for (not only) macromolecular structure data. Mol* development was jointly initiated by PDBe and RCSB PDB to combine and build on the strengths of [LiteMol](https://litemol.org) (developed by PDBe) and [NGL](https://nglviewer.org) (developed by RCSB PDB) viewers.

When using Mol*, please cite:

David Sehnal, Sebastian Bittrich, Mandar Deshpande, Radka Svobodová, Karel Berka, Václav Bazgier, Sameer Velankar, Stephen K Burley, Jaroslav Koča, Alexander S Rose: [Mol* Viewer: modern web app for 3D visualization and analysis of large biomolecular structures](https://doi.org/10.1093/nar/gkab314), *Nucleic Acids Research*, 2021; https://doi.org/10.1093/nar/gkab314.

### Protein Data Bank Integrations

- The [pdbe-molstar](https://github.com/molstar/pdbe-molstar) library is the Mol* implementation used by EMBL-EBI data resources such as [PDBe](https://pdbe.org/), [PDBe-KB](https://pdbe-kb.org/) and [AlphaFold DB](https://alphafold.ebi.ac.uk/). This implementation can be used as a JS plugin and a Web component and supports property/attribute-based easy customisation. It provides helper methods to facilitate programmatic interactions between the web application and the 3D viewer. It also provides a superposition view for overlaying all the observed ligand molecules on representative protein conformations.

- [rcsb-molstar](https://github.com/molstar/rcsb-molstar) is the Mol* plugin used by [RCSB PDB](https://www.rcsb.org). The project provides additional presets for the visualization of structure alignments and structure motifs such as ligand binding sites. Furthermore, [rcsb-molstar](https://github.com/molstar/rcsb-molstar) allows to interactively add or hide of (parts of) chains, as seen in the [3D Protein Feature View](https://www.rcsb.org/3d-sequence/4hhb).


## Project Structure Overview

The core of Mol* consists of these modules (see under `src/`):

- `mol-task` Computation abstraction with progress tracking and cancellation support.
- `mol-data` Collections (integer-based sets, interface to columns/tables, etc.)
- `mol-math` Math related (loosely) algorithms and data structures.
- `mol-io` Parsing library. Each format is parsed into an interface that corresponds to the data stored by it. Support for common coordinate, experimental/map, and annotation data formats.
- `mol-model` Data structures and algorithms (such as querying) for representing molecular data (including coordinate, experimental/map, and annotation data).
- `mol-model-formats` Data format parsers for `mol-model`.
- `mol-model-props` Common "custom properties".
- `mol-script` A scripting language for creating representations/scenes and querying (includes the [MolQL query language](https://molql.github.io)).
- `mol-geo` Creating (molecular) geometries.
- `mol-theme` Theming for structure, volume and shape representations.
- `mol-repr` Molecular representations for structures, volumes and shapes.
- `mol-gl` A wrapper around WebGL.
- `mol-canvas3d` A low-level 3d view component. Uses `mol-geo` to generate geometries.
- `mol-state` State representation tree with state saving and automatic updates.
- `mol-plugin` Allow to define modular Mol* plugin instances utilizing `mol-state` and `mol-canvas3d`.
- `mol-plugin-state` State transformations, builders, and managers.
- `mol-plugin-ui` React-based user interface for the Mol* plugin. Some components of the UI are usable outside the main plugin and can be integrated into 3rd party solutions.
- `mol-util` Useful things that do not fit elsewhere.

Moreover, the project contains the implementation of `servers`, including

- `servers/model` A tool for accessing coordinate and annotation data of molecular structures.
- `servers/volume` A tool for accessing volumetric experimental data related to molecular structures.
- `servers/plugin-state` A basic server to store Mol* Plugin states.

The project also contains performance tests (`perf-tests`), `examples`, and `cli` apps (CIF to BinaryCIF converter and JSON domain annotation to CIF converter).

## Previous Work
This project builds on experience from previous solutions:
- [LiteMol Suite](https://www.litemol.org)
- [WebChemistry](https://webchem.ncbr.muni.cz)
- [NGL Viewer](http://nglviewer.org)
- [MMTF](http://mmtf.rcsb.org)
- [MolQL](http://molql.org)
- [PDB Component Library](https://www.ebi.ac.uk/pdbe/pdb-component-library/)
- And many others (list will be continuously expanded).

## Building & Running

### Build:
    npm install
    npm run build

### Build automatically on file save:
    npm run watch

If working on just the viewer, ``npm run watch-viewer`` will provide shorter compile times.

### Build with debug mode enabled:
    DEBUG=molstar npm run watch

Debug/production mode in browsers can be turned on/off during runtime by calling ``setMolStarDebugMode(true/false, true/false)`` from the dev console.

### Cleaning and forcing a full rebuild
    npm run clean

Wipes the `build` and `lib` directories and `.tsbuildinfo` files.

    npm run rebuild

Runs the cleanup script prior to building the project, forcing a full rebuild of the project.

Use these commands to resolve occasional build failures which may arise after some dependency updates. Once done, `npm run build` should work again. Note that full rebuilds take more time to complete.

### Develop with `esbuild`

Experimental support for faster builds with `esbuild`
- `npm run dev:all` - watch mode for all apps and examples
- `npm run dev:viewer` - watch mode for viewer
- `npm run dev:apps` - watch mode for all apps
- `npm run dev:examples` - watch mode for all examples
- `npm run dev -- -a <app name 1> <app name 2> -e <example name 1> ...` - watch mode for specified apps/examples. `-a`/`-e` with without any names will build everything.

### Build for production:
    NODE_ENV=production npm run build

**Run**

If not installed previously:

    npm install -g http-server

...or a similar solution.

From the root of the project:

    http-server -p PORT-NUMBER

and navigate to `build/viewer`

### Code generation
**CIF schemas**

    node ./lib/commonjs/cli/cifschema -mip ../../../../mol-data -o src/mol-io/reader/cif/schema/mmcif.ts -p mmCIF
    node ./lib/commonjs/cli/cifschema -mip ../../../../mol-data -o src/mol-io/reader/cif/schema/ccd.ts -p CCD
    node ./lib/commonjs/cli/cifschema -mip ../../../../mol-data -o src/mol-io/reader/cif/schema/bird.ts -p BIRD
    node ./lib/commonjs/cli/cifschema -mip ../../../../mol-data -o src/mol-io/reader/cif/schema/sf.ts -p SF
    node ./lib/commonjs/cli/cifschema -mip ../../../../mol-data -o src/mol-io/reader/cif/schema/cif-core.ts -p CifCore -aa

**Lipid names**

    node lib/commonjs/cli/lipid-params -o src/mol-model/structure/model/types/lipids.ts

**Ion names**

    node --max-old-space-size=8192 lib/commonjs/cli/chem-comp-dict/create-ions.js src/mol-model/structure/model/types/ions.ts

**Saccharide names**

    node --max-old-space-size=8192 lib/commonjs/cli/chem-comp-dict/create-saccharides.js src/mol-model/structure/model/types/saccharides.ts

### Other scripts
**Create chem comp bond table**

    node --max-old-space-size=8192 lib/commonjs/cli/chem-comp-dict/create-table.js build/data/ccb.bcif -b

**Test model server**

    export NODE_PATH="lib"; node build/src/servers/model/test.js

**State Transformer Docs**

    export NODE_PATH="lib"; node build/state-docs

**Convert any CIF to BinaryCIF (or vice versa)**

    node lib/commonjs/servers/model/preprocess -i file.cif -ob file.bcif

To see all available commands, use ``node lib/commonjs/servers/model/preprocess -h``.

Or

    node lib/commonjs/cli/cif2bcif

E.g.

    node lib/commonjs/cli/cif2bcif src.cif out.bcif.gz
    node lib/commonjs/cli/cif2bcif src.bcif.gz out.cif

## Development

### Installation

If node complains about a missing acorn peer dependency, run the following commands

    npm update acorn --depth 20
    npm dedupe

### Editor

To get syntax highlighting for shader files add the following to Visual Code's settings files and make sure relevant extensions are installed in the editor.

    "files.associations": {
        "*.glsl.ts": "glsl",
        "*.frag.ts": "glsl",
        "*.vert.ts": "glsl"
    },

## Publish

### Prerelease
    npm version prerelease # assumes the current version ends with '-dev.X'
    npm publish --tag next

### Release
    npm version 0.X.0 # provide valid semver string
    npm publish

## Deploy
To prepare apps and demos for https://molstar.org deploy, run:

    npm run test
    npm run deploy:local

To commit these changes remotely to the `molstar/molstar.github.io` repo:

    npm run deploy:remote

## Contributing
Just open an issue or make a pull request. All contributions are welcome.

## Funding
Funding sources include but are not limited to:
* [RCSB PDB](https://www.rcsb.org) funding by a grant [DBI-1338415; PI: SK Burley] from the NSF, the NIH, and the US DoE
* [PDBe, EMBL-EBI](https://pdbe.org)
* [CEITEC](https://www.ceitec.eu/)
* [EntosAI](https://www.entos.ai)

---
_Source: https://npm.io/package/molstar · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._