Architecture

Tangly is a thin layer over Astro 6. Your project is docs.json + *.mdx; Tangly synthesizes an Astro app, loads your content via virtual modules, and renders prerendered HTML through a single catch-all route.

High-level flow

flowchart TD
  subgraph user[Your project]
    A1[docs.json]
    A2["*.mdx files"]
    A3[images/, logo/, public/]
  end

  subgraph cli[tangly CLI]
    B1["@tanglydocs/schema<br/>parse + validate"]
    B2[manifest builder]
    B3[Vite plugin<br/>virtual modules + middleware]
  end

  subgraph runtime[Tangly runtime]
    C1["catch-all<br/>[...slug].astro"]
    C2[Astro content collection<br/>glob over user root]
    C3[MDX components<br/>auto-injected]
  end

  subgraph out[Output]
    D1[dist/]
  end

  A1 --> B1 --> B2
  A2 --> B2
  B2 --> B3
  A2 --> C2 --> C1
  C3 --> C1
  B3 -. virtual:tangly/* .-> C1
  A3 --> B3
  C1 --> D1

The flow is one-directional: parse → manifest → expose → render → emit. Dev mode watches the user directory and re-emits virtual modules on change; build mode runs once.

Three packages

Key design decisions

Performance targets

• Cold dev start: under 2s for 100 pages.
• HMR: under 250ms.
• Build: under 30s for 100 pages.

These are acceptance criteria, not aspirations. Profile before merging if anything regresses.

Read more