Live example

Astroc4 in action

This page is the plugin dogfooding itself. Every diagram below is compiled by astroc4 during this site’s build, from a real .c4 model of purview.dev, and hydrated as a React island in your browser. Nothing here is a screenshot.

Read the guide

Project page

Source

1. One component, the site’s own model

The model lives in src/likec4. Astroc4 compiles it once with LikeC4’s Vite plugin, and <LikeC4View> picks a view from it. The view is interactive: hover a node, scroll to zoom, click an element to open its details.

Click any node to open the modal

Loading architecture diagram…

The page writes one component and the plugin does the rest: the model is compiled at build time, laid out by LikeC4, and the browser only hydrates the resulting JSON.

---
title: Architecture
---

import LikeC4View from '@purview-dev/astroc4/components/LikeC4View.astro';

<LikeC4View viewId="index" height={520} />

2. A fence whose DSL is the page

A ```likec4 fence in an .mdx page is a diagram, not a code block. The DSL in the fence is compiled and laid out during the build, so the diagram is reviewed in the same diff as the prose around it. Below is a small model of the request that produced the page you are reading.

Loading diagram…

A typo in that DSL fails astro build with the fence’s file name and the parser message, rather than shipping a blank frame. The layout is memoised by the source text, so a page re-rendered during development pays for each distinct snippet once.

3. The same model, a different view

An empty fence names a view instead of carrying DSL. This one renders the deployment view from the same .c4 file as the first diagram, so the two can never tell different stories about production.

Click any node to open the modal

Loading architecture diagram…

LikeC4 source, highlighted without config

Shiki has no LikeC4 grammar, so astroc4 derives one from LikeC4’s own Langium language definition and injects it into Starlight’s Expressive Code options. There is no ec.config.mjs in this repository. A ```c4 fence shows the source rather than drawing it.

specification {
  color brand #8B3DFF
  element actor { style { shape person } }
  element system { style { color brand } }
}

model {
  reader = actor 'Reader'
  site = system 'purview.dev' {
    #public
    icon tech:astro
    docs = service 'Documentation portal' {
      #internal
      technology 'Astro + Starlight'
    }
  }
  reader -[https]-> docs 'reads'
}

5. The details that make it hold up

Icons from the grammar

tech:astro in the model above is a bundled pack icon. The pack list is read from LikeC4’s LIB_ICON terminal, so a pack upstream adds highlights and renders without a change here. Self-hosted icons stay under public/; LikeC4’s imageAliases bakes a build-machine file:// path into the bundle and is deliberately unsupported.

Translated shell

The frame headings, badges and error messages come from Starlight’s i18n system. A site that ships a second locale gets the diagram UI in it for free, and any key can be overridden in src/content/i18n/<lang>.json.

Reproducible highlighting

This site pins the grammar to v1.60.0. The grammar is fetched once per repo@ref, cached and ETag-revalidated; a build that cannot reach raw.githubusercontent.com fails by default, or falls back to the bundled snapshot with offline: true. ASTROC4_REF overrides the ref from CI without editing the config.

Static by default, hydrated on demand

The diagram has no useful server-rendered form, so it is a client:only=“react” island with a placeholder that carries the frame height. A static build passes even when islands fail to hydrate, which is why astroc4’s own CI runs a browser smoke test rather than trusting the exit code.

Use it in your own site

Astroc4 is published to npm. The full set of options — fences, the Vite plugin workspace, highlighting, cache and failure policy — is in the

configuration reference

Get started

Back to Astroc4