elkjs

elkjs brings the layout-computation core of the Eclipse Layout Kernel (ELK) to JavaScript, so applications can automatically compute node and edge positions for diagrams without implementing a layout algorithm themselves. Its flagship algorithm is a layered, Sugiyama-style layout well suited to node-link diagrams with an inherent direction and explicit ports (attachment points on a node’s border), the kind of structure common in flowcharts, data-flow diagrams, and dependency graphs.

elkjs is explicitly scoped to layout computation only — it does not render, style, or draw anything, leaving that to a diagramming framework such as Sprotty, D3, or a custom SVG/canvas renderer that consumes elkjs’s computed coordinates. It is the JavaScript successor to the earlier klayjs project and tracks ELK’s Java implementation, with releases loosely synchronized to upstream ELK version numbers.

What You Get

• A layered (Sugiyama-style) automatic layout algorithm suited to directional node-link diagrams with ports
• A pure layout API (elk-api.js) separate from the worker that performs the computation (elk-worker.js), plus a bundled browser build (elk.bundled.js)
• Support for incremental and dynamic layout scenarios, including adding nodes/edges to an existing layout
• Configurable layout options mirroring ELK’s Java configuration surface (direction, spacing, port constraints, edge routing)
• A Node.js-friendly entry point (main.js) for require('elkjs')/import usage without manually composing the API and worker files
• TypeScript typings for the layout graph input/output shapes

Common Use Cases

• Automatically laying out flowcharts, BPMN diagrams, or state machines rendered with a separate diagramming library
• Computing node/edge positions for dependency graphs, data-flow diagrams, or pipeline visualizations
• Powering the layout step of interactive diagram editors (e.g. alongside Sprotty) where users can still manually adjust positions after auto-layout
• Laying out graphs with explicit ports, such as circuit diagrams or diagrams where edges must attach to specific sides of a node
• Providing consistent, algorithmic diagram layout in tools that previously required manually positioned nodes

Under The Hood

Architecture - elkjs separates the public layout API (src/js, compiled to elk-api.js) from the actual layout engine (elk-worker.js), which is generated from ELK’s original Java codebase (src/java, src/java-additional) via GWT (Google Web Toolkit) cross-compilation rather than being hand-written in JavaScript. This means elkjs’s core layout logic is a transpiled port of a mature, actively developed Java project (Eclipse ELK), while the thin JavaScript API layer handles calling into that generated worker and shaping the input/output graph JSON.

Tech Stack - The build pipeline spans two ecosystems: Gradle (build.gradle, gradlew) drives the Java-to-JavaScript GWT compilation of the layout engine, while Babel and Browserify (babel src/js/, browserify ... -s ELK) produce the JavaScript-facing API and bundled browser build from src/js. This dual-toolchain setup is a direct consequence of porting rather than reimplementing ELK’s algorithms.

Code Quality - Tests live under test/mocha and test/examples, run via mocha test/mocha, and the project’s README maintains an explicit, actively curated FAQ of recurring GitHub issues (module resolution errors from the GWT-generated code, poor modularization, dynamic/incremental layout requests), showing the maintainers directly track and document the rough edges inherent to the Java-to-JS porting approach.

API Design - The API takes a plain graph object (nodes, edges, ports, layout options) and returns a promise resolving to the same graph annotated with computed positions, keeping the surface framework-agnostic so any renderer can consume the output. The tradeoff of the GWT-generated worker is a less idiomatic JavaScript experience in places (documented issues like g is not defined under certain bundler configurations), which the README addresses directly rather than hiding.