BPMN 2.0 Editor — making bpmn-js feel like it belongs.
A modern process-modelling editor embedded in a single-spa shell, built on bpmn-js inside a Material UI host that I did not get to choose. Two engineers, eighteen months, enterprise scale.
What it looks like
The problem
An enterprise client had a process-modelling tool from 2014 that nobody on staff remembered how to extend.
They needed something modern, BPMN 2.0-compliant, and embedded inside their existing single-spa portal without rewriting the host.
The approach
We treated bpmn-js as a third-party canvas, not a UI framework. The React layer owned the file picker, sidebar, export dialog, toolbar, and application state.
Communication happened through a small adapter that translated React props into bpmn-js commands and bpmn-js events back into React state.
The interesting decisions live at the boundary between two libraries that do not quite agree about state ownership.From the v0.6 retro
The hard bits
- —State ownership. bpmn-js wants to own the diagram document. React wants to own UI state. The adapter is small but every method earns its keep.
- —Exports. SVG is easy; PNG needs a canvas dance; PDF was a server round-trip on a Lambda we wrote ourselves.
- —Material UI versus bpmn-js CSS. Two libraries both thought they owned z-index, so bpmn-js styles were isolated inside their own layer.
- —Keyboard shortcuts. Twenty-two shortcuts, all configurable and rebindable.
What I'd do differently
I would write the export Lambda first. We pushed it to the end and it became the rate-limiting step of the rollout.
I would also be louder, earlier, about not using Material UI for new work inside the host.
The 22 shortcuts
Read another case study
Mongo → Postgres — zero-downtime migration
A two-way sync, a phased cutover, and a healthcare platform that stayed online for the entire migration.