renderizr

Renderizr — a Structurizr workspace as one shareable file

This skill renders a Structurizr workspace — its views, documentation and decision log — into a browsable static site, or into a single self-contained HTML file that you can upload as a Claude artifact and anyone can open, with no server and no network.

Renderizr draws the diagrams with its own engine from everything the workspace says (positions, styles, themes, shapes and routing), so they pan, zoom and animate dynamic views the way they do in Structurizr.

When to use this skill

• The user wants to see an architecture model rather than read its source.
• The user wants to share a model with people who have no Structurizr account, no server and no copy of the DSL.
• The user asks for an artifact, a preview, or "publish the diagrams".
• The user works in a repository that has an ./architecture folder — often one created by Scaffoldizr — and wants output from it.

Do not use this skill to author or edit a model: that is Scaffoldizr's job. Renderizr renders a workspace, and its edit mode (npx renderizr edit) lets a person arrange the layout of its views in a browser; the agent never drives edit mode.

The one command

npx github:FormulaMonks/renderizr <workspace.json|url> --single-file --out <dir>

That writes two files into <dir>:

File	What it is	Use it for
artifact.html	The page without its own <html>/<head>/<body> scaffolding	Uploading as a Claude artifact — the host supplies the document
index.html	The same page as a complete standalone document	Opening from disk, emailing, dropping in a bucket

Both inline every stylesheet, script, font, icon and the workspace itself. Neither makes a single network request.

For a Claude artifact, use artifact.html. Handing over index.html instead produces a document nested inside a document.

Drop --single-file to get a directory — index.html plus assets/ — for hosting on a static server or GitHub Pages.

Getting a workspace to render

Renderizr takes JSON, either a local path or a URL. It does not parse DSL.

• A workspace.json already on disk — usually ./architecture/workspace.json. Use it directly.

• Only a workspace.dsl — export it first with structurizr-cli, which exports a DSL workspace to JSON. In a Scaffoldizr repository, ./architecture/scripts/export.sh (or export.ps1) does this for you.

• A URL — passed straight through, e.g. the Big Bank plc example:

  npx github:FormulaMonks/renderizr \
    https://raw.githubusercontent.com/structurizr/structurizr/main/structurizr-export/src/test/resources/big-bank-plc.json \
    --single-file --out /tmp/big-bank
  

In a Scaffoldizr repository workspace.json holds the views' layout as well as the exported model: Renderizr's edit mode and Structurizr Local save layout into it, and Structurizr's merge keeps that layout when the DSL changes. Render it, and never edit it by hand.

Recommended flow

1. Find the workspace. Look for ./architecture/workspace.json. If only workspace.dsl exists, export it first and say so; do not silently render a stale JSON. An export that overwrites a workspace.json holding layout loses it: when one exists, export with merge -layout workspace.json.

2. Render it, into a temporary directory rather than the repository, unless the user asked you to keep the output:

   npx github:FormulaMonks/renderizr ./architecture/workspace.json --single-file --out /tmp/renderizr-out
   

3. Check it is genuinely self-contained before handing it over — see verifying. One command, and it is the difference between an artifact that opens and one that renders blank for the recipient.

4. Hand over artifact.html. Say which file it is and roughly how big; a real model lands around 1 MB. When you publish it as a Claude artifact yourself, declare the downloads capability (for example capabilities: {downloads: true}), so the reader can export views.

Flags

Full reference in flags. The ones that matter most:

Flag	Effect
--single-file	One self-contained document, plus artifact.html. Use for artifacts.
-o, --out <dir>	Output directory (default structurizr-output)
--base <path>	Base public path for the multi-file build, e.g. /repo-name/ for project Pages
--logo <path|url>	Image top-left in the header, embedded as a data URI
--font <family>	A Google Web Font, fetched at build time and embedded as woff2

--font and a remote --logo are the only things that need network access during a build. Without them a render is fully offline.

Things that will bite you

We verified each of these against the tool:

• Node 20 is a hard floor. npx runs against whatever Node is first on PATH, which is often not the one the shell reports. Renderizr checks and exits with a clear message rather than failing deep inside the build.
• artifact.html and index.html are not interchangeable. See the table above.
• An artifact without downloads can't export. The artifact viewer lets a page save a file only through its downloads capability. Publish artifact.html without declaring it and the page hides its export buttons.
• Renderizr empties the output directory before writing. Never point --out at a directory holding anything you want to keep.
• https:// in the output is not a leak. A rendered page contains ordinary hyperlinks to structurizr.com, c4model.com and the like. Self-containment is about asset references — <script src>, <link href>, <img src> — of which there are none. Check the right thing; see verifying.
• Working inside a clone of the Renderizr repository is different. pnpm render <workspace> [flags] — and specifically not pnpm render -- <workspace> --flag, which makes the flag arrive as a second workspace. pnpm dev is the opposite and does want the --. This only applies inside the repository; npx users are unaffected.

References

• flags — every CLI flag, what it does, and what it costs
• artifacts — the Claude artifact path in detail, including size and what to hand over
• verifying — proving an artifact is self-contained before you hand it over