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