CindyJS is a CindyScript interpreter with a geometry engine attached

Two components: a language and a geometry toolkit

CindyJS is described as a framework to create interactive mathematical content for the web, and the README explains its shape in two sentences. It aims to be compatible with Cinderella, providing an interpreter for the scripting language CindyScript as well as a set of geometric operations which can be used to describe constructions. Together, those components make it easy to visualize various concepts, from geometry in particular and mathematics in general, but also from various other fields.

That pairing is what makes it more than a plotting library. A drawing API takes coordinates and gives you a picture. CindyJS takes a program, in a language whose primitives are points, lines, circles, conics and transformations, and evaluates it, so a figure is the result of the construction rather than a set of hand placed shapes.

The compatibility goal also sets the expectations. CindyJS is not a general purpose scripting host; it is an implementation of a specific dialect designed to be interchangeable with a desktop tool, and anything in the documentation that goes beyond that dialect is out of scope. The project home is cindyjs.org, and the licence is Apache 2.

The reference documentation is a goal, not a status report

The API documentation lives in the repository rather than on a separate site. The CindyJS API documentation, at `ref/createCindy.md`, describes how to create a widget on an HTML page using the framework, and the rest of the `ref` directory describes large portions of the CindyScript programming language.

The README is unusually blunt about the state of that documentation. It says the documentation started as a copy of the corresponding Cinderella documentation, and that it is currently meant as a goal of what functionality should be supported, while actual support might still be lagging behind. If you have a particular feature you need, the README's advice is to file a feature request.

That is the single most important thing to know before adopting the project. A page of documented functions tells you the intended language, not the implemented one. The realistic workflow is to read the reference for the shape of the language, then verify each operation you rely on against the examples, which the README describes as demonstrating individual functions and operations.

The examples also have a gallery online at cindyjs.org, so a reader can see what working constructions look like before committing to the framework at all.

The examples directory doubles as the test bed

The `examples` directory inside the repository holds one HTML file per feature, and the file names are a catalogue of what the framework does. There is a playground, a sunflower, a complex spiral, a parabola envelope, a simple geometry example, a sine caustic, a convex hull, field lines, a regression example, polar operations, a slider, an example explicitly named bad elements, several arc variants, and a line width example.

Developers can run these examples from a local development copy, and the README explains the catch. Some examples may require a webserver-like environment to avoid triggering browser security measures associated with local files. To do so, one can run `node_modules/.bin/st -l -nc` in the root of the development tree and then visit the local copy of the examples directory at http://127.0.0.1:1337/examples/.

That command comes from the `st` package in the development dependencies, and it is worth understanding why the workaround exists. Opening the files directly with a `file://` URL puts the page in a restricted origin, and the browser then blocks the kind of cross-file access the examples rely on. Serving them over HTTP from a local port removes the restriction, which is why the README treats a webserver as a requirement for some examples rather than a convenience.

Make is a thin wrapper around a JavaScript build system

The build is unusual enough to be worth reading before you try it. If you have npm installed, running `npm install` in the top level source directory should just work. If you lack a compatible setup of npm and node, running `make build=release` in the top level source directory should get a suitable setup installed inside the project directory tree, and in general all required third-party tools should be automatically downloaded and installed inside the project directory tree.

The Makefile itself is small, because it delegates. The first target is:

all: js_make
	$(JS_MAKE)

and the cleaning target is:

clean:
	$(RM) -r build

Most of the work happens in the `make` directory, which contains a JavaScript-based build system, and the README says pretty much all the commands are in fact passed on to it. The `build=release` argument is the switch between build modes, and the Makefile also resolves a Node.js runtime of its own, downloading a pinned version into the project tree when the system does not have a usable one.

One dependency cannot be automated. The README notes one exception to the automatic download of third-party tools: a Java Runtime Environment has to be installed beforehand, because users have to manually accept the terms and conditions before being allowed to download a JRE.

The outputs are predictable. After a successful build, `build/js` contains the artefacts you would likely want to include in a web site, and if you are building from an official commit, `make build=release deploy` creates `build/deploy`, which is better suited to a web server since it references the commit at GitHub and that reference can help diagnose problems.

On Windows, the Makefile is optional

The README handles Windows in a short section. The description of the build uses make mostly for convenience, and pretty much all the commands are in fact passed on to the JavaScript-based build system in the `make` directory. If you do not have make available on Windows, you can call `node make` instead, so a standard release build would be `node make build=release`.

Three things have to be installed first, and the README lists them as requirements: a recent Java Runtime Environment, Node.js with the `node` command added to the PATH, and Git for Windows with the `git` command usable from the Windows Command Prompt.

The `node make` entry point is the useful thing to remember, because it removes make from the equation entirely. Everything the Makefile does is available through Node, which means a Windows developer and a Linux developer are running the same build system with the same arguments.

A fast debug build and a slow release build

The contributing section draws a distinction that decides how you will work in the repository. When you work on the code base, the simple `make` or `node make` will give you a build which is fast to compile and easy to debug. In contrast, `node make build=release` will perform additional compilation steps like running the Closure Compiler. It may issue more warnings, which in turn might be useful when developing. The README asks that you make sure your code works in both build modes.

Testing follows a defined route. If you are confident that your work is done, call `make alltests` after you did `git add` to stage your changes, and that will ensure your modifications pass all kinds of tests. The same tests will be run automatically on pull requests. Once modifications satisfy your expectations, pass these tests and are accompanied by a suitable test case or demonstrating example where appropriate, you may file a pull request.

That last clause is the project's convention for a change. A pull request is expected to carry either a test or a demonstration, and the examples directory is the natural place for the latter, since every feature there already has a named HTML file.

A multi-language codebase with a plugin and editor layer

The repository is larger than a single library. At the top level there are `src/`, `lib/`, `plugins/`, `editor/`, `make/`, `tools/`, `tests/`, `benchmarks/`, `ref/`, `examples/`, `css/` and `images/`, an `Administration/` directory, a `CSExtensions.txt` file, a `Makefile`, a `package.json` and a `tsconfig.json`.

The development dependencies explain what the project is made of: `mocha` and `chai` for the test suite, `@playwright/test` for browser level testing, `browser-sync` and `st` for the local example server, `esbuild` and `babel` for the JavaScript pipeline, `sass` for the stylesheets, `katex` for typesetting, `gl-matrix` for linear algebra, `@jscad/csg` for solid modelling, `webxr-polyfill` for immersive output, and a fork of `leapjs`. There is also `marked` for Markdown, `pako` for compression, `rewire` for reaching into modules from tests, and `prettier` and `eslint` for style, with `husky` and `lint-staged` wiring the checks into commits.

Releases are frequent and incremental: the tags are v0.8.47 from 2026-10-10, v0.8.46 from 2026-06-19 and v0.8.45 from 2026-06-05, and the last push was on 2026-10-14. The version in `package.json` reads 0.0.1, so the published version comes from the tag rather than from the manifest. The licence is Apache 2, which is the permissive choice you would want for a framework that is embedded in teaching pages and republished on other sites.

Editorial conclusion

Adopt CindyJS when you need to publish interactive geometry or mathematics that runs in a browser page without a plugin, and when the Cinderella compatible CindyScript dialect and its construction vocabulary fit your subject. Do not adopt it expecting the documented language surface to be implemented, because the reference documentation describes a goal rather than the current state, and do not treat the build as a single command on a machine without a Java runtime. Verify first that the operations your lesson needs are present by working through the examples in the examples directory, that the release build and the debug build both work for your change, and that the version you ship is the tag v0.8.47 from 2026-10-10 given that the last push was on 2026-10-14.

Frequently asked questions

Official sources

1. CindyJS/CindyJS on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases