sigma.js: WebGL graph rendering on top of graphology

The rendering library and the graph library are separate

The one-sentence description is precise about the scale and the technique: an open-source JavaScript library aimed at visualizing graphs of thousands of nodes and edges using WebGL. Thousands is the operative word. The library is not trying to be a general graph analysis package, and the repository topics confirm the narrow focus, listing webgl, graph, graphs, graph-drawing, graph-drawing-framework, data-visualization and javascript.

The architectural decision is that sigma.js is built on top of graphology. Graphology is a separate project that owns the graph data structure, and sigma.js takes a graph object and renders it. That separation shows up in the install step, where both packages come together:

npm install sigma graphology

Most graph libraries bundle their own data structure, which sounds convenient until you want to use the same graph in two places. Here the graph is a value you can hold, serialize and pass around, and the renderer is a view onto it. If you already keep your graph in graphology for analysis, adding a renderer does not mean migrating anything.

The project credits two primary developers, jacomyal and Yomguithereal. Both names recur across the wider ecosystem, and the fact that the renderer is credited to two people rather than a team is a reasonable signal about the size of the codebase.

Three lines to a rendered graph

The usage example in the README is the whole getting-started story, and it is worth reading closely because the API tells you what the library expects of you.

import Graph from "graphology";
import Sigma from "sigma";

Then a graph gets built with explicit visual attributes on each node and edge:

const graph = new Graph();
graph.addNode("1", { label: "Node 1", x: 0, y: 0, size: 10, color: "blue" });
graph.addNode("2", { label: "Node 2", x: 1, y: 1, size: 20, color: "red" });
graph.addEdge("1", "2", { size: 5, color: "purple" });

const sigmaInstance = new Sigma(graph, document.getElementById("container"));

Four things fall out of that. Coordinates are your responsibility: `x`, `y`, `size` and `color` are supplied by the caller, which means sigma renders rather than lays out. A layout algorithm is a separate concern you plug in before rendering. Node and edge attributes are plain properties on the graph, so anything you attach is carried through. And the constructor takes a container element, so the renderer owns a DOM node you provide.

That last point is the one that changes how you use the library. Because the container is yours, you can put a graph anywhere in a page, including inside a panel or a tab that does not exist at first render. Because layout is yours, you can re-run a physics simulation and let sigma redraw, which is what an interactive graph needs and what a hardcoded coordinate example cannot show.

The example assigns the instance to a variable, which matters more than it looks. A renderer held only in a local scope gets collected, and a graph that disappears from the screen with no error is a confusing failure mode.

A monorepo built on npm workspaces and preconstruct

The repository tree shows a monorepo, and the root `package.json` shows how it is wired. Workspaces are declared as `packages/*`, the build script runs preconstruct and then a bundle step scoped to the sigma workspace, and tests are delegated to a dedicated `@sigma/test` workspace.

  "workspaces": [
    "packages/*"
  ],

Preconstruct is the tool doing the work of letting many packages point at each other during development without a build step, which is why there is a `postinstall` script running `preconstruct dev` and a `postpublish` script doing the same thing. Development is a matter of running `preconstruct dev` and then the Storybook, which is what `npm run start` does.

The local development path is documented as four commands, and the fourth one is the point of the Storybook setup:

git clone [email protected]:jacomyal/sigma.js.git
cd sigma.js
npm install
npm run start

Storybook opens in the browser and live reloads when stories or package sources change. For a rendering library this is the correct choice, because the only way to judge a graph renderer is to look at graphs. The storybook is also published as its own site, and there is a separate demo that the root scripts describe as a full-featured React-based web application, which doubles as a reference for how the library sits inside a component-based app.

Linting and formatting are separate concerns: eslint with a flat config file, prettier with an import-sorting plugin, and a clean script that removes node_modules across workspaces. `prepublishOnly` runs test, then build, then lint, so a publish cannot bypass any of the three.

Adding a package with one script

Not every decision in this repository is about rendering, and the new-package script is the clearest example. Running `npm run createPackage` from the project root asks for a package name, then copies `packages/template` and updates the new package's `package.json` entries for name, description and exports.

It also updates the files that list the packages. The script touches the buildable packages list in `tsconfig.json` and the Preconstruct-compatible packages list in the root `package.json`. That second point is the reason the script exists at all: in a monorepo with workspaces, adding a package means updating several registration points, and forgetting one produces a confusing failure rather than an obvious one.

The other structural details worth noticing are small. There is a `lerna.json` alongside npm workspaces, a `bin/` directory holding the create-package script itself written in TypeScript and run through ts-node, a `.prettierrc.json` for formatting, and a CHANGELOG.md. The website, demo and storybook builds are orchestrated from the root with a script that copies the demo build and the storybook static output into the website build directory, which is how all three end up served from one domain.

For a contributor, the contribution rules are short: open issues and pull requests, and make sure tests and linting pass before submitting. CONTRIBUTING.md is linked for the detail.

Version 4 exists as an alpha with an empty changelog

The most important line in the README is a note rather than a paragraph. Sigma v4 is available as an alpha release, with its own website at v4.sigmajs.org and its own branch named `v4`, separate from the `main` branch the README otherwise describes.

The release feed gives the alpha cadence. Three beta tags are visible: `[email protected]` published 2026-08-18, `[email protected]` on 2026-08-20, and `[email protected]` on 2026-09-16. Every one of them has an empty name and an empty body, so the release metadata tells you when a beta shipped and nothing about what changed. For a library where a rendering upgrade can change how your graph looks or how your reducers are wired, that absence is worth planning around: the migration notes are not in the release feed.

The tag naming itself is informative. Tags are scoped to the package rather than to the repository, using the package name and version, which is the convention preconstruct sets up. It means releases are per-package, so a package in the monorepo can ship without sigma itself shipping.

The last push to `main` was on 2026-09-16, the same day as the sixth beta. The project is moving, and the 12 open issues against 1,620 forks suggests the maintenance load is light for a library of this size. License is MIT, stated in the LICENSE.txt at the repository root and in the root package metadata, so the licensing question does not need to influence the decision.

Where to read past the README

The README hands off to three destinations and one credit. The documentation site is built with Docusaurus and carries the guides and API references that a rendering library actually needs: settings, events, reducers, edge and node programs. The Storybook is the visual catalogue of what those settings do. The demo is the integration reference, a React application rather than a snippet.

The credit is worth repeating because it tells you something about the project. The website was designed by Robin de Mourat of the Sciences-Po médialab team. A graph library whose presentation layer is good enough to attract a design commission from a research lab is making a different argument from most rendering libraries, and the documentation site is where that argument is visible.

What the README does not cover, and what the documentation site therefore has to, is the interesting part of the API. Reducers and edge and node programs are the extension mechanism, and they are the answer to the question the two-line example cannot answer: how do you make this graph respond to hovering, filtering or selection without reimplementing the renderer. If you are evaluating the library, that is the page to read after the example, because it decides how much work your application ends up owning.

Editorial conclusion

sigma.js is worth reaching for when your graph has more nodes than a DOM renderer can survive, and the reason is that the split of responsibility is clean: graphology owns the graph, sigma owns the pixels, and neither one asks you to give up the other's strength. Twelve thousand stars with only a dozen open issues is an unusual ratio, and it lines up with a project whose scope is deliberately narrow. The v4 alpha is the open question rather than a settled one, with six beta tags and empty release bodies, so treat it as something to evaluate against your own renderer needs rather than something to adopt on faith. MIT licensing means there is no commercial decision to make first. Start with the two-line install and the example constructor call, and if you intend to extend the library rather than use it, the create-package script and the template folder are the two things worth reading before your first pull request.

Frequently asked questions

Official sources

1. jacomyal/sigma.js on GitHub
2. License: MIT
3. Project website
4. README
5. Releases