WebCola hands back coordinates and leaves the drawing to you

Constraint solving for graphs that come with rules

WebCola is a layout engine rather than a drawing library, and that boundary decides what you can build with it. The project's one-line description calls it a constraint-based graph layout in TypeScript, and the keywords declared in package.json run Graph, Layout, Constraints, Optimization. You hand it nodes and links, attach rules where the arrangement is not free, and it gives back coordinates. Two demos linked at the top of the README cover exactly two of those rule families: a small world graph carrying simple groups, and a separate page demonstrating alignment constraints. Teams that hand-place nodes in a diagram, or that pick a general charting library and then nudge positions by eye until nothing overlaps, are the ones with a real case for this package.

Coordinates come out, rendering stays with your library

Whatever leaves the solver is a position rather than a picture, which pushes drawing, hit testing and interaction into your own code. The README's summary line says the library is for graph visualization and exploration using D3.js and other web-based graphics libraries, so the output is not bound to one renderer. That claim shows up in the repository layout too: the top-level entries are the src, `test`, `tasks` and `website` directories plus `cypress.json` and the rollup and TypeScript config files, with no separate drawing package to import. Nothing in that file list promises a component you can drop into a page and consider finished. It is a deliberate trade, and the effect is to move the work you keep rather than remove it.

Three install paths, one of them typed through tsd

The browser route is two script tags pointing at the hosted copies, one minified and one full, and a page that already loads D3 needs nothing else:

<script src="https://ialab.it.monash.edu/webcola/cola.min.js"></script>
<script src="https://ialab.it.monash.edu/webcola/cola.js"></script>

Use one or the other, since loading both defines the same globals twice. The minified file is also reachable from jsDelivr, and package managers cover the remaining routes. For a bundled project the npm install is a single line:

npm install webcola --save

Adding the entry to package.json before installing works the same way:

"dependencies": {
  "webcola": "latest"
}

A Bower route is documented too:

bower install webcola --save

TypeScript users get pointed at tsd 0.6 from DefinitelyTyped and told to run `tsd link`, which is an unusual route given that package.json resolves types from a file inside the published package.

The README build recipe predates the tsdx scripts

Here a close reading pays off. The build section still presents node, a plain install, a build and a test as the whole workflow, and it states that the build creates `cola.js` and `cola.min.js` in the dist directory:

npm install
npm run build
npm run test

package.json describes something else. Its build script is `tsdx build --name cola --format esm,umd`, a postbuild step runs the typings script, and that typings script executes `tsc -p tsconfig.dts.json` followed by `rollup -c rollup.dts.config.js`. No step in that chain emits a file called cola.js. The names the README promises and the names the package points at are two different sets, and anyone who follows the prose while watching the dist directory will conclude the build failed.

Entry points that disagree with the documented output files

Four fields in package.json decide what your code actually loads:

"main": "dist/cola.umd.development.js",
"module": "dist/cola.esm.js",
"unpkg": "dist/cola.umd.production.min.js",
"jsdelivr": "dist/cola.umd.production.min.js"

`main` resolves to the development build, so a CommonJS consumer pulls the unminified bundle with no minification step of its own. Bundlers that prefer `module` get the ESM file, and a plain script tag through unpkg or jsDelivr gets the minified one. Types come from `dist/cola.d.ts`, and the files array ships only the `dist` and `src` directories, so the source travels with the package. The consequence is easy to miss: which build you ship depends on which field your tool honours, not on anything the README explains.

A test command configured to pass with no tests

The unit command behind `npm run test` is `tsdx test --passWithNoTests`, and the watch and coverage variants carry the same flag. Read literally, that flag lets the run exit green when no test file is found, so a clean result on a fresh clone tells you little about correctness. Verification effort sits elsewhere in the repository: there is a `cypress.json`, a `cypress` directory at the top level, and scripts named `cy:run`, `cy:open` and `cy:junit`, the last of which writes a mochaFile report. There is also a `tsconfig.example.json` driven by `compile-examples`, which means the example pages are type checked as their own project.

A D3 v3 style interface over a two-version adaptor

One sentence in the README sets the integration cost: while the D3 adaptor supports both D3 v3 and D3 v4, the interface is styled like D3 v3, and the setup details live on the homepage rather than in the repository. D3 version 4 rewrote selection handling, so application code written against the newer style will not read the way the calls in this package expect. The devDependencies list `@types/d3` at `^4.5.0`, the typing line for D3 4 rather than anything newer, and the adapter is there to smooth over the difference rather than to erase it. Treat it as a compatibility layer and plan a small amount of glue when the rest of your page has moved on.

Where this layout engine stops and your code starts

The operational answers are thinner than the API description. The project homepage is http://marvl.infotech.monash.edu/webcola/, while every script tag and the homepage link in the README point at a different host, ialab.it.monash.edu. The jsDelivr address adds another wrinkle: its path names a ref, WebCola, that is neither the default branch master nor a numbered build, so a page loading that file can receive something other than what npm installs. There is no rollback procedure, no dated history of solver changes and no migration note between the older cola.js layout and the packaged one, leaving a team that upgrades to compare output coordinates by hand. The last push was on 2026-04-30 and the newest numbered build is v3.3.8 from 2018-03-19, while the version field in package.json already reads 3.4.0. The MIT licence lets you embed the layout code inside a product you never open source, which is the one adoption question that carries no follow-up work.

Editorial conclusion

Adopt WebCola when the graph carries rules a general drawing library will not express, groups or alignment between nodes that must not drift, and when you already own the rendering layer. Do not adopt it expecting a ready-made viewer or build files named the way its README claims. Before committing, install it from npm, check which entry point your bundler resolves, and compare the returned coordinates against your current D3 version. And do not trust a green unit run, because that command passes when it finds nothing.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tgdwyer/WebCola on GitHub