131 lines
3.1 KiB
Markdown
131 lines
3.1 KiB
Markdown
# D2.js
|
|
|
|
[](https://www.npmjs.com/package/@terrastruct/d2)
|
|
[](https://mozilla.org/MPL/2.0/)
|
|
|
|
D2.js is a JavaScript wrapper around D2, the modern diagram scripting language. It enables running D2 directly in browsers and Node environments through WebAssembly.
|
|
|
|
## Features
|
|
|
|
- 🌐 **Universal** - Works in both browser and Node environments
|
|
- 🚀 **Modern** - Built with ESM modules, with CJS fallback
|
|
- 🔄 **Isomorphic** - Same API everywhere
|
|
- ⚡ **Fast** - Powered by WebAssembly for near-native performance
|
|
- 📦 **Lightweight** - Minimal wrapper around the core D2 engine
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# npm
|
|
npm install @terrastruct/d2
|
|
|
|
# yarn
|
|
yarn add @terrastruct/d2
|
|
|
|
# pnpm
|
|
pnpm add @terrastruct/d2
|
|
|
|
# bun
|
|
bun add @terrastruct/d2
|
|
```
|
|
|
|
## Usage
|
|
|
|
D2.js uses webworkers to call a WASM file.
|
|
|
|
```javascript
|
|
// Same for Node or browser
|
|
import { D2 } from '@terrastruct/d2';
|
|
// Or using a CDN
|
|
// import { D2 } from 'https://esm.sh/@terrastruct/d2';
|
|
|
|
const d2 = new D2();
|
|
|
|
const result = await d2.compile('x -> y');
|
|
const svg = await d2.render(result.diagram, result.options);
|
|
```
|
|
|
|
Additional Configuration:
|
|
|
|
```javascript
|
|
import { D2 } from '@terrastruct/d2';
|
|
|
|
const d2 = new D2();
|
|
|
|
const result = await d2.compile('x -> y', {
|
|
sketch = true,
|
|
});
|
|
const svg = await d2.render(result.diagram, result.options);
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### `new D2()`
|
|
|
|
Creates a new D2 instance.
|
|
|
|
### `compile(input: string, options?: CompileOptions): Promise<CompileResult>`
|
|
|
|
Compiles D2 markup into an intermediate representation.
|
|
|
|
### `render(diagram: Diagram, options?: RenderOptions): Promise<string>`
|
|
|
|
Renders a compiled diagram to SVG.
|
|
|
|
### `CompileOptions`
|
|
|
|
All `RenderOptions` properties in addition to:
|
|
|
|
- `layout`: Layout engine to use ('dagre' | 'elk') [default: 'dagre']
|
|
|
|
### `RenderOptions`
|
|
|
|
- `sketch`: Enable sketch mode [default: false]
|
|
- `themeID`: Theme ID to use [default: 0]
|
|
- `darkThemeID`: Theme ID to use when client is in dark mode
|
|
- `center`: Center the SVG in the containing viewbox [default: false]
|
|
- `pad`: Pixels padded around the rendered diagram [default: 100]
|
|
- `scale`: Scale the output. E.g., 0.5 to halve the default size. The default will render SVG's that will fit to screen. Setting to 1 turns off SVG fitting to screen.
|
|
- `forceAppendix`: Adds an appendix for tooltips and links [default: false]
|
|
|
|
### `CompileResult`
|
|
|
|
- `diagram`: `Diagram`: Compiled D2 diagram
|
|
- `options`: `RenderOptions`: Render options merged with configuration set in diagram
|
|
- `fs`
|
|
- `graph`
|
|
|
|
## Development
|
|
|
|
D2.js uses Bun, so install this first.
|
|
|
|
### Building from source
|
|
|
|
```bash
|
|
git clone https://github.com/terrastruct/d2.git
|
|
cd d2/d2js/js
|
|
./make.sh all
|
|
```
|
|
|
|
If you change the main D2 source code, you should regenerate the WASM file:
|
|
```bash
|
|
./make.sh build
|
|
```
|
|
|
|
### Running the dev server
|
|
|
|
You can browse the examples by running the dev server:
|
|
|
|
```bash
|
|
./make.sh dev
|
|
```
|
|
|
|
Visit `http://localhost:3000` to see the example page.
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome!
|
|
|
|
## License
|
|
|
|
This project is licensed under the Mozilla Public License Version 2.0.
|