bpmn-js: rendering and editing BPMN 2.0 diagrams in the browser

What bpmn-js solves, and who actually needs it

BPMN 2.0 is an XML interchange format. A .bpmn file is a document with semantic elements (tasks, events, gateways, sequence flows) plus diagram interchange data that says where each shape sits on a canvas. Rendering that correctly in a browser is a graphics and layout problem before it is a business-process problem. bpmn-js exists to absorb that problem.

The README describes the project as a way to "view and edit BPMN 2.0 diagrams in the browser." That sentence defines the audience narrowly. This is for engineers building a product that has to show or manipulate process diagrams: a workflow designer inside an internal tool, an editor embedded in a BPM platform, a review screen that displays a process someone else authored. It is not for someone who wants to open a .bpmn file on their desktop. There is no desktop application here, and no server component.

The distinction matters because people arrive at bpmn-js expecting a product. The repository is a library. The demo at demo.bpmn.io is a demonstration of the library, not the deliverable. If you need an end user to model a process without writing any code, this is the wrong layer of the stack.

The rendering pipeline: bpmn-moddle in, diagram-js on screen

The README names the two dependencies bpmn-js is built on, and they map cleanly onto the two halves of the problem. bpmn-moddle handles "read / write support for BPMN 2.0 XML in the browsers." diagram-js provides "diagram rendering and editing toolkit." bpmn-js sits between them: it takes the parsed BPMN model and drives diagram-js to draw and manipulate it.

That layering is the reason the toolkit is extensible. diagram-js is a generic diagramming engine that knows about shapes, connections, canvases and interaction; it does not know what a BPMN gateway is. bpmn-js supplies the BPMN-specific vocabulary on top. When you import XML, the flow runs from raw string to moddle parse to internal element tree to rendered shapes. When the user drags a task, the change flows back through the model and can be serialized to XML again.

The README also points to "many additional utilities" in the bpmn-io ecosystem. Those are separate packages, not bundled features. The practical consequence is that a bare bpmn-js instance gives you a canvas and the standard BPMN modeling interactions, while anything beyond that (a properties panel, for instance) is a further dependency you add yourself. That is a deliberate design choice and it keeps the core install small, but it also means the first hour with the library is spent discovering which capabilities live outside it.

Installing bpmn-js from npm and rendering your first diagram

The README gives two installation routes: use the library "pre-packaged" or include it "via npm" into a node-style web application. The examples repository linked from the README has separate directories for each, so pick the one that matches your build setup rather than mixing them.

For the npm route, install the package and import it. The README's own usage example creates an instance and imports a BPMN 2.0 XML string:

const xml = '...'; // my BPMN 2.0 xml
const viewer = new BpmnJS({
  container: 'body'
});

try {
  const { warnings } = await viewer.importXML(xml);

  console.log('rendered');
} catch (err) {
  console.log('error rendering', err);
}

The container option accepts a selector, so 'body' renders the diagram into the whole page. The importXML call returns a promise. On success you get an object with a warnings array, which is where the parser reports non-fatal problems in the XML; on failure the promise rejects and you land in the catch block. A diagram that renders with warnings is still rendered, so log the array rather than ignoring it.

If you want to run the project itself rather than consume the package, the README documents the development commands. Dependencies install first:

npm install

Then a single local modeler instance starts with:

npm start

The README notes that npm start is shorthand for SINGLE_START=modeler, and that start:viewer and start:navigated-viewer exist for the other two modes. For a full development setup with the test watcher, the command is npm run dev. Running the complete build and test suite is npm run all. The README warns that the latest development snapshot "may" need additional project setup documented in docs/project/SETUP.md, so read that file if the build fails on the develop branch.

Where bpmn-js stops being the right tool

The library renders in the browser. There is no documented server-side rendering path in the README, and no headless mode. If your requirement is to turn a .bpmn file into a PNG on a build server, this is not the component for that job, and no amount of configuration will make it one.

The second limitation is scope. bpmn-js models BPMN 2.0, a notation for business processes. It is not a general flowchart editor and not a decision table tool. Teams sometimes reach for it because BPMN diagrams look like flowcharts, then discover that the element palette and validation rules are BPMN-specific. If your users think in free-form boxes and arrows, the BPMN vocabulary will feel like a constraint rather than a feature.

The third limitation is that the core library is a canvas, not an application. Undo history, persistence, user permissions, collaboration and a properties panel are all outside it. The README lists a properties panel among the related searches people use, and it is worth stating plainly: the properties panel is not part of what you get from the core package. Budget for assembling several packages before you have something a non-engineer can use.

How bpmn-js differs from a general diagramming library

The obvious alternative approach is a general-purpose diagramming library such as a graph or canvas toolkit, where you define your own node types and connection rules. The difference is not cosmetic. With a general library you write the model, the serialization format, the validation and the palette yourself. With bpmn-js, the BPMN 2.0 metamodel, the XML read and write support and the standard element set arrive already implemented through bpmn-moddle.

That trade runs in both directions. You get interoperability for free: files produced by bpmn-js are BPMN 2.0 XML, which other BPMN tools can read. You also inherit BPMN's constraints, including element types your users may never need and rules about what can connect to what. A general diagramming library imposes none of that, but it also gives you nothing, and you would be reimplementing a specification that already exists.

A second alternative is to embed a third-party BPMN editor as a hosted service. That removes the build and the licence question from your plate, at the cost of sending process definitions to someone else's infrastructure and depending on their uptime. bpmn-js keeps the diagram in your page, which is the reason many teams choose it.

Licence, maintenance and the cost of upgrading

The package.json declares the licence as NOASSERTION, and the README says to use the library "under the terms of the bpmn.io license," linking to bpmn.io/license. That is not an OSI identifier and not a standard SPDX string. Automated licence scanners will flag it, and some organisations will refuse it outright. Read the linked terms yourself and get whatever sign-off your company requires; this is a commercial-terms question, not a legal opinion anyone can hand you in a review.

The repository is not archived, and the last push was on 2026-09-21. Releases are frequent and versioned: v18.29.1 on 2026-09-21, v18.29.0 on 2026-09-21, and v18.28.0 on 2026-09-04. That cadence is a real upgrade cost. The version number is at 18.x, so major bumps have happened many times, and a library that moves this quickly will occasionally change module behaviour. Pin your version, and read CHANGELOG.md before bumping rather than after.

The build itself is not trivial to reproduce. npm run all chains linting, theme validation, tests, type generation, the distro build and a distro test. The package also runs a prepare script that builds the distro on install and a prepublishOnly script that regenerates TypeScript declarations. If you vendor the source rather than consuming the published package, you inherit that toolchain.

Editorial conclusion

Adopt bpmn-js if you need a BPMN 2.0 canvas embedded in a web application and you are willing to read the bpmn.io licence terms before shipping. Do not adopt it if you need a hosted modeling product, a server-side renderer, or a permissively licensed dependency with no attribution conditions. Before committing, verify three things: that the bpmn.io license text covers your distribution model, that the bpmn-js-examples repository has a sample matching your bundler, and that the properties panel is a separate package rather than part of the core install.

Frequently asked questions

Official sources

1. bpmn-io/bpmn-js on GitHub
2. Issues
3. Project website
4. README
5. Releases