d2/d2js/js

D2.js

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

# 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.

// 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);

Configuring render options (see CompileOptions for all available options):

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.renderOptions);

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

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:

./make.sh build

Running the dev server

You can browse the examples by running the dev server:

./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.