Meltemi Diagrams

Español

Professional diagrams written as code, adjusted on a canvas, animated and exported, part of the Meltemi family. You write .meltemi text files; the editor draws them beside the code, and every drag, resize or label change on the canvas becomes a small edit of the same text. Code, layout and motion live in files you review and version like the rest of your work.

• Five profiles: flow diagrams, sequence diagrams with scenarios, C4 views of a shared model, free compositions for slides, and gantt charts for plans and roadmaps.
• Code and canvas: language services and a canvas with a grid, guides, routing and an inspector, in VS Code and in the web app.
• Motion: effects along connectors and stories with scenes, camera and transitions.
• Delivery: SVG, PNG, vector PDF, an offline HTML player, MP4, WebM, GIF and a browsable catalog of a whole project.
• Coming from elsewhere: Mermaid and PlantUML importers that report every construct.
• Local and open: MIT licensed, no account, nothing leaves your machine; AI assistance is optional.

Install

npm install --global @meltemi/diagrams-cli

The command is meltemi-diagrams, or mdg. It needs Node 22.12 or later; PNG, PDF and video use an installed Edge or Chrome, and video an installed FFmpeg. The editor is the Meltemi Diagrams extension for VS Code, and the web app, at diagrams.meltemi.dev, needs no installation at all (the web app, getting started).

A first diagram

meltemi-diagrams init shop

language "0.2"

diagram overview: flow {
  title "Overview"
  direction LR

  client["Client"]
  api["API"] { description "Handles requests" }
  db[("Database")]

  client -> api: "HTTPS" as request
  api -> db: "Reads and writes" as store
}

meltemi-diagrams export shop --format png

Open the file in VS Code to drag the boxes on the canvas, or run meltemi-diagrams preview shop --open to see every change as you save.

Trying it from this repository

Everything can be tried from a checkout, before or without anything published. You need Node 22.12 or later and pnpm 10; PNG, PDF and video use an installed Edge or Chrome, and video an installed FFmpeg.

Set up once

pnpm install

pnpm build

The command line

pnpm mdg runs the command from the sources; paths are relative to the repository's root.

pnpm mdg init try-it --template purchase

pnpm mdg validate try-it

pnpm mdg preview try-it --open

preview serves the project's catalog on http://127.0.0.1:4317/ and redraws it every time a .meltemi file is saved: edit a file under try-it/diagrams/ in any editor and watch it change. Then export it:

pnpm mdg export try-it --format png

pnpm mdg export try-it/stories/purchase.meltemi --story purchase --format mp4

pnpm mdg build catalog try-it

To use the command from any folder, as if it were installed, point a shell function at the built command (after pnpm build), replacing the path with your checkout's. In PowerShell:

function mdg { node C:\path\to\meltemi-diagrams\packages\cli\dist\bin.js @args }

In Bash:

mdg() { node /path/to/meltemi-diagrams/packages/cli/dist/bin.js "$@"; }

The editor in VS Code

Package the extension and install it:

pnpm vscode:package

code --install-extension packages/vscode/meltemi-diagrams.vsix

Open the try-it folder in VS Code and any .meltemi file in it: the canvas opens beside the code. Drag a box, double-click a label, or connect two boxes from the dots beside a selected one, and watch the text change. Without installing anything, open this repository in VS Code and press F5 with Run Meltemi Diagrams: an Extension Development Host opens on examples/ (editor).

The web app

pnpm playground:build

pnpm preview

Then open http://localhost:4173/packages/playground/dist/. pnpm preview serves the whole repository on port 4173, so exported files can be opened from it too (the web app).

What is already generated

No command is needed to look at these:

• gallery/README.md: the five profiles with their SVG, PNG and PDF exports;
• examples/purchase/exports/catalog/index.html: the purchase example's catalog, which opens from disk and works offline;
• examples/purchase/exports/purchase-story.html: the story in the HTML player;
• docs/media/editing-demo.mp4: the editing demo.

Checking everything

pnpm test

pnpm acceptance

pnpm release:check

pnpm test runs every package's tests. pnpm acceptance runs every acceptance criterion in about twelve minutes and records the results in docs/quality/results.md. pnpm release:check builds and packs every package, installs the command from the packed files into an empty folder, never from the registry, and runs it there: the closest thing to a published release (releasing).

This is the beginning of the README. Read the rest at the original. Read the full README ↗