1# bpmn-js - BPMN 2.0 for the web
2
3[![Build Status](https://github.com/bpmn-io/bpmn-js/workflows/CI/badge.svg)](https://github.com/bpmn-io/bpmn-js/actions?query=workflow%3ACI)
4
5View and edit BPMN 2.0 diagrams in the browser.
6
7[![bpmn-js screencast](./resources/screencast.gif "bpmn-js in action")](http://demo.bpmn.io/s/start)
8
9
10## Installation
11
12Use the library [pre-packaged](https://github.com/bpmn-io/bpmn-js-examples/tree/master/pre-packaged)
13or include it [via npm](https://github.com/bpmn-io/bpmn-js-examples/tree/master/bundling)
14into your node-style web-application.
15
16## Usage
17
18To get started, create a [bpmn-js](https://github.com/bpmn-io/bpmn-js) instance
19and render [BPMN 2.0 diagrams](https://www.omg.org/spec/BPMN/2.0.2/) in the browser:
20
21```javascript
22const xml = '...'; // my BPMN 2.0 xml
23const viewer = new BpmnJS({
24  container: 'body'
25});
26
27try {
28  const { warnings } = await viewer.importXML(xml);
29
30  console.log('rendered');
31} catch (err) {
32  console.log('error rendering', err);
33}
34```
35
36Checkout our [examples](https://github.com/bpmn-io/bpmn-js-examples) for many
37more supported usage scenarios.
38
39
40### Dynamic Attach/Detach
41
42You may attach or detach the viewer dynamically to any element on the page, too:
43
44```javascript
45const viewer = new BpmnJS();
46
47// attach it to some element
48viewer.attachTo('#container');
49
50// detach the panel
51viewer.detach();
52```
53
54
55## Resources
56
57* [Demo](http://demo.bpmn.io)
58* [Issues](https://github.com/bpmn-io/bpmn-js/issues)
59* [Examples](https://github.com/bpmn-io/bpmn-js-examples)
60* [Forum](https://forum.bpmn.io)
61* [Changelog](./CHANGELOG.md)
62
63
64## Build and Run
65
66Prepare the project by installing all dependencies:
67
68```sh
69npm install
70```
71
72Then, depending on your use-case you may run any of the following commands:
73
74```sh
75# build the library and run all tests
76npm run all
77
78# spin up a single local modeler instance
79npm start
80
81# run the full development setup
82npm run dev
83```
84
85You may need to perform [additional project setup](./docs/project/SETUP.md) when
86building the latest development snapshot.
87
88
89## Related
90
91bpmn-js builds on top of a few powerful tools:
92
93* [bpmn-moddle](https://github.com/bpmn-io/bpmn-moddle): Read / write support for BPMN 2.0 XML in the browsers
94* [diagram-js](https://github.com/bpmn-io/diagram-js): Diagram rendering and editing toolkit
95
96
97## Contributing
98
99Please checkout our [contributing guidelines](./.github/CONTRIBUTING.md) if you plan to
100file an issue or pull request.
101
102
103## Code of Conduct
104
105By participating to this project, please uphold to our [Code of Conduct](https://github.com/bpmn-io/.github/blob/master/.github/CODE_OF_CONDUCT.md).
106
107
108## License
109
110Use under the terms of the [bpmn.io license](http://bpmn.io/license).
111