https://github.com/bpmn-io/bpmn-js-headless

Run bpmn-js in headless environments
https://github.com/bpmn-io/bpmn-js-headless

bpmn-js

Last synced: 3 months ago
JSON representation

Run bpmn-js in headless environments

• Host: GitHub
• URL: https://github.com/bpmn-io/bpmn-js-headless
• Owner: bpmn-io
• Created: 2023-08-10T12:58:27.000Z (about 1 year ago)
• Default Branch: main
• Last Pushed: 2024-04-03T08:27:51.000Z (7 months ago)
• Last Synced: 2024-04-14T11:10:10.189Z (7 months ago)
• Topics: bpmn-js
• Language: JavaScript
• Homepage:
• Size: 211 KB
• Stars: 1
• Watchers: 6
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

• awesome-bpmn-io - bpmn-js-headless - Execute [bpmn-js](https://github.com/bpmn-io/bpmn-js) in headless environments (Extensions)

README

        
> [!WARNING]

> This is an experimental library and not officially supported / endorsed by [bpmn.io](https://bpmn.io/). See also [caveats](#caveats).

# bpmn-js-headless

[![CI](https://github.com/bpmn-io/bpmn-js-headless/actions/workflows/CI.yml/badge.svg)](https://github.com/bpmn-io/bpmn-js-headless/actions/workflows/CI.yml)

Run [bpmn-js](https://github.com/bpmn-io/bpmn-js) in headless environments.

## Usage

Use just like [bpmn-js](https://github.com/bpmn-io/bpmn-js), but be sure not to use interactive (extension) modules.

```javascript

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

const modeler = new BpmnModeler();

// import diagram

await modeler.importXML(myDiagram);

// perform a change operation

modeler.invoke((modeling, elementRegistry) => {

  const participant = elementRegistry.get('Participant_1');

  modeling.removeElements([ participant ]);

});

// export diagram

const {

  xml

} = await modeler.saveXML({ format: true });

```

## Why?

This utility is useful whenever you want to apply complex modeling operations in headless (aka no browser) environments. Some examples:

* Apply [element templates](https://github.com/bpmn-io/element-templates)

* Build BPMN diagrams [programmatically](https://github.com/nikku/bpmn-js-cli-modeling-dsl)

## How does it work

* Uses only bpmn-js modules that are safe for headless execution

* Overrides core [diagram-js](https://github.com/bpmn-io/diagram-js) components to be independent of graphical representation

## Caveats

This is a truely headless version of bpmn-js, i.e. it does not fake a browser environment. For extensions to be compatible they shall enforce a proper UI / behavior separation, and not rely on browser features.

You want to bundle this library along with extensions, as [bpmn-js](https://github.com/bpmn-io/bpmn-js) and dependent libraries require bundling, too.