Derafu: Vite Plugin D2 - A Vite plugin to convert D2 diagrams to Images
A Vite plugin that converts D2 diagram files to SVG during the build process.
Installation
npm install --save-dev vite-plugin-d2
Make sure you have D2 installed globally:
npm install -g d2
Or follow the official installation instructions at: https://d2lang.com/tour/install/
Usage
Add the plugin to your vite.config.js
:
import vitePluginD2 from 'vite-plugin-d2';
export default {
plugins: [
vitePluginD2({
// Options (all optional).
theme: 0, // D2 theme (number).
layout: 'dagre', // Layout engine.
sketch: false, // Enable sketch mode.
dark: false, // Enable dark mode.
pad: 10, // Padding.
diagramsDir: './assets/diagrams', // Input directory for D2 files.
outputDir: null, // Custom output dir (uses Vite's outDir if null).
outputFormat: 'svg', // Output format (currently only 'svg').
verbose: false // Enable verbose output logging.
})
]
};
How it works
The plugin searches for .d2
files in the specified directory (diagramsDir
, defaults to ./assets/diagrams
). During the build process, this plugin will:
- Find all
.d2
files in the specified directory. - Convert them to SVG using the D2 CLI.
- Place the generated SVG files in the output directory.
For example, if you have:
./assets/diagrams/architecture.d2
The plugin will generate:
./dist/architecture.svg
(or in your configured output directory).
Output Directory Configuration
By default, the plugin will output the SVG files to Vite’s configured build output directory (build.outDir
, which defaults to dist
).
You can customize the output location by setting the outputDir
option. The relative structure of files within the diagramsDir
will be preserved in the output.
Example D2 File
# Example D2 diagram.
shape: sequence_diagram
actor User
app: Application
db: Database
User -> app: Request data
app -> db: Query
db -> app: Results
app -> User: Display data
Options
Option | Type | Default | Description |
---|---|---|---|
theme | number | 0 | D2 theme number |
layout | string | ‘dagre’ | Layout engine (e.g., ‘dagre’, ‘elk’) |
sketch | boolean | false | Enable sketch/hand-drawn mode |
dark | boolean | false | Enable dark mode |
pad | number | 10 | Padding around the diagram |
diagramsDir | string | ‘./assets/diagrams’ | Directory containing D2 files |
outputDir | string|null | null | Custom output directory (uses Vite’s build.outDir if null) |
outputFormat | string | ‘svg’ | Output format (currently only ‘svg’ is supported) |
verbose | boolean | false | Enable verbose output logging |
Advanced Usage
Custom Input and Output Directories
You can specify custom directories for your D2 files and the generated SVGs:
vitePluginD2({
diagramsDir: './src/diagrams', // Custom input directory.
outputDir: './public/images', // Custom output directory.
verbose: true // Enable detailed logging.
})
Styling Options
Customize the appearance of your diagrams:
vitePluginD2({
theme: 3, // Use theme number 3.
sketch: true, // Enable sketch mode for hand-drawn appearance.
dark: true, // Enable dark mode.
pad: 20 // Add more padding (20px).
})
Troubleshooting
If you encounter issues:
- Make sure D2 is properly installed and available in your PATH.
- Check if the input directory exists and contains .d2 files.
- Enable verbose mode (
verbose: true
) to see detailed logs. - Verify you have the necessary permissions to write to the output directory.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
License
This package is open-sourced software licensed under the MIT license.