Migrating our Libraries to ES Modules | Blog

We are proud to announce the latest release of our BPMN rendering toolkit as well as its underlying foundations. Ported to ES modules, this release represents a major effort in modernizing our code base.

Modularity is an important aspect of our toolkit landscape and the enabler for extensibility. ES modules, standardized via ES2015, is the first module system baked directly into JavaScript as a language feature. ES modules improve code readability and the fact that they are statically analyzable allows module bundlers to apply advanced minification strategies such as tree shaking.

In the last weeks we've cut several releases that migrate our libraries to ES modules:

We shipped a full rewrite of our DMN toolkit with ES modules inside two weeks ago. In addition, we have ported our CMMN toolkit to use ES module dependencies under the hood.

Consuming ES Modules

If you use our pre-packaged distributions, nothing changes for you. Otherwise, consider migrating to our latest toolkit versions a breaking change that requires a number of adjustments to your code base.

Usage from ES6

If you are already using ES import / export as part of your application, make sure to use individual parts of utilities via destructuring:

import BpmnModeler from 'bpmn-js/lib/Modeler';

import {
  is
} from 'bpmn-js/lib/util/ModelUtil';

The reason for that change is that utilities do not publish default exports.

Usage from CommonJS

When consuming our libraries from CommonJS, access default module exports via the default property:

var BpmnModeler = require('bpmn-js/lib/Modeler').default;

var is = require('bpmn-js/lib/util/ModelUtil').is;

Checkout this commit to our CMMN toolkit for a good example how to migrate your CommonJS codebase to build on top of a ES module dependency.

Bundling ES Modules

Since most browsers do not support ES modules yet you must bundle your application and our libraries with an ES module aware bundler such as Rollup, Webpack or Browserify + babelify. Learn more about it in our reworked bundling example.

If you are using Browserify as your build tool, take a look at how we integrated babelify into the cmmn-js build pipeline in order to migrate the library to diagram-js@1.

Changelogs Everywhere

We celebrate the ES module transition with a number of major releases. Along with these releases we introduced changelogs to all of our projects. Read through the individual toolkit changelogs to understand the important changes that landed into certain library versions. As we use semantic versioning you'll be able to learn about potential breaking changes, too.

As an example, read about all changes since bpmn-js@0.31, the last ES5 version of bpmn-js in the libraries' changelog.

Are you passionate about JavaScript, modeling, and the web?
Join Camunda and build modeling tools people .