gridgram

Grid-based diagram rendering — describe a diagram as a TypeScript DiagramDef or a .gg text file, get a clean SVG. Built on Preact SSR; runs in modern browsers and in Node.

import { tablerOutline, renderDiagramSvg, type DiagramDef } from 'gridgram'

const def: DiagramDef = {
  nodes: [
    { id: 'user', src: tablerOutline('user'), label: 'User' },
  ],
}

const svg = renderDiagramSvg(def)

Or embed it directly in your Preact JSX:

import { Diagram } from 'gridgram'

export function ArchitectureDiagram() {
  return <Diagram def={def} renderWidth={1024} />
}

Two surfaces share one pipeline:

• TypeScript API (npm install gridgram) — this package. SVG only.
• gg CLI — a single-binary build of the same engine that also emits PNG (via sharp). Install from GitHub Releases.

Install

npm install gridgram
# or
bun add gridgram

Requires an ESM environment. preact and preact-render-to-string are peer-ish runtime deps resolved through your bundler (Vite, webpack, esbuild, Rollup, Bun, Node ≥22 ESM, …).

Quick example

import {
  renderDiagram,
  tablerOutline,
  type DiagramDef,
} from 'gridgram'

const def: DiagramDef = {
  nodes: [
    { id: 'user', pos: 'A1', src: tablerOutline('user'),    label: 'User' },
    { id: 'web',  pos: 'B1', src: tablerOutline('world'),   label: 'Web'  },
    { id: 'db',   pos: 'C1', src: tablerOutline('database'),label: 'DB'   },
  ],
  connectors: [
    { from: 'user', to: 'web', label: 'request' },
    { from: 'web',  to: 'db',  label: 'query'   },
  ],
}

const { svg, diagnostics } = renderDiagram(def, { renderWidth: 1024 })
// svg: a standalone <svg …>…</svg> string
// diagnostics: [] on clean layouts; non-empty when labels / connectors
//              couldn't be placed cleanly

API surface

| Export | Shape | Use when | |-----------------------|-----------------------------------------------------------------|-------------------------------------------------------------| | renderDiagram | (def, opts?) => { svg, diagnostics } | Default choice. You want the SVG plus layout feedback. | | renderDiagramSvg | (def, opts?) => string | You only need the SVG. | | Diagram | Preact functional component (<Diagram def={…} />) | Embedding in a Preact app. | | buildDiagramTree | (def, opts?) => VNode | Embedding the VNode without going through renderToString. | | tabler, tablerOutline, tablerFilled, tablerHas | Icon lookups by name (e.g. 'user', 'arrow-right') | Using Tabler icons as node src. | | BADGE_PRESETS, expandBadges | Named corner-badge presets + expander | Decorating nodes with status badges. | | defineConfig, resolveSettings, SYSTEM_DEFAULTS | Layered settings merge | Shared defaults across many diagrams. |

Every type used in DiagramDef (NodeDef, ConnectorDef, RegionDef, NoteDef, DiagramTheme, GridPos, GridSpan, …) is re-exported.

Options

renderDiagram(def, opts) / <Diagram def={…} …opts /> accepts:

| Option | Type | Description | |------------------|-----------|------------------------------------------------------------------------| | renderWidth | number | Final output width in px; height scales with aspect. | | cellSize | number | Pixel size of one grid cell (default 256). | | padding | number | Inner padding in px. | | columns, rows| number | Force the grid size (otherwise inferred from node positions). | | theme | partial | Deep-merged against the built-in theme (primary, accent, bg, …). | | suppressErrors | boolean | Hide the red-tint markers drawn when a label can't be placed cleanly. |

opts is merged on top of any settings the DiagramDef embeds (def.cellSize, def.theme, …), so you can set project-wide defaults on the def and override per-call.

Icons

gridgram ships the Tabler icon set (5500+ outline, 1200+ filled) with zero setup:

import { tablerOutline, tablerFilled } from 'gridgram'

tablerOutline('user')      // '<g fill="none" stroke="currentColor">…</g>'
tablerFilled('star')       // filled variant, or undefined if none exists

Or use any raw SVG string / Preact VNode as src on a node — gridgram doesn't care where the icon came from.

Diagnostics

The pipeline reports layout issues as structured diagnostics instead of throwing. Each record names the element, the failure kind (label-collision, route-failed, icon-unresolved, …), and the attempts it made:

const { svg, diagnostics } = renderDiagram(def)
for (const d of diagnostics) {
  console.warn(d.kind, d.message, d.element)
}

Use the red-tint markers in the SVG to find the problem visually, or the diagnostics list to surface it in tests / CI.

.gg text format & CLI

For diagrams embedded in docs or wikis there's a text format (.gg) with a Mermaid-ish DSL and doc { } command blocks. The gg CLI renders them to SVG / PNG / JSON:

gg diagram.gg -o out.svg
gg diagram.gg -o out.png --width 2048

gg render diagram.gg -o out.svg       # explicit form (same as above)
gg icons --search database            # search 6,000+ built-in Tabler icons
gg icons --tag cloud --limit 20       # or filter by tag
gg llm                                # emit the full LLM reference bundle
gg license                            # bundled third-party notices

The CLI is built on citty and ships as a single self-contained binary from the GitHub Releases page — no npm install required.

AI-agent integrations

gridgram is built for LLM-driven workflows out of the box:

• gg llm emits a one-shot Markdown (or --format json) reference covering the .gg grammar, CLI surface, doc { } settings, icon resolution, JSON envelope shape, and canonical examples. Drop it into an agent's context to eliminate guesswork.
• gg icons provides semantic search over 5,039 outline + 1,053 filled Tabler icons with a scored query model (name / label / tags / category). src/data/icon-tags.json adds gridgram-authored synonyms so common architecture terms (cache, microservice, kubernetes, loadbalancer, …) surface the right generic icons.
• /llms.txt and /llms-full.txt on the docs site index and concatenate every page plus the LLM reference.
• context7.json registers gridgram with context7 so agents can fetch the docs over MCP.
• Claude Code / gh skill plugin at plugins/gridgram — install via the ideamans/claude-public-plugins marketplace to get /gg-render, /gg-icons, and /gg-author skills. The same SKILL.md bundle is compatible with gh skill install, Cursor, Gemini CLI, Codex, and any other host that speaks the Agent Skills open standard.

Runtime support

• Browsers — any ESM-friendly bundler (Vite, Rspack, esbuild, …). SVG only.
• Node ≥ 22 — native ESM with import attributes. SVG only.
• Bun — any recent version. SVG only.
• PNG — CLI-only, via the gg binary.

License

MIT — see LICENSE. Bundled third-party notices (Tabler icons, Preact, json5, sharp, …) are reproduced in THIRD_PARTY_LICENSES.md, and the gg binary prints the same text via gg --license.

PNG output is CLI-only and depends on libvips (LGPL-2.1-or-later). The gg binary does not bundle it: on first PNG render, sharp and a prebuilt libvips for your platform are fetched from the npm registry into ~/.cache/gridgram/ and loaded dynamically, so the LGPL library remains user-replaceable.