An open source design system that's fully customizable and agent ready
Astryx Docsite
The OSS documentation site for Astryx. Built with Next.js and StyleX.
Quick Start
pnpm install # from repo root
pnpm build # build all packages (themes need built exports)
cd apps/docsite
pnpm generate # extract data from the monorepo into src/generated/
pnpm dev # start the dev server
pnpm dev and pnpm build both run generate automatically via predev/prebuild scripts.
How It Works
The docsite never hardcodes package lists, component catalogs, or theme maps.
Everything flows through a build-time data pipeline that extracts information
from the monorepo and writes typed TypeScript registries to src/generated/.
The Pipeline
scripts/generate-data.mjs scans the monorepo and produces:
| Registry | Source | What it contains |
|---|---|---|
packageRegistry.ts |
packages/*/package.json |
Name, version, description, README for each published package |
componentRegistry.ts |
Core + CLI-configured integration .doc.mjs files |
Props, usage docs, hooks, groups, per package |
componentPreviewRegistry.ts |
Components from those same packages | Runtime exports for the shared Properties preview |
blockRegistry.ts |
CLI + integration template blocks | Showcase and example blocks with metadata |
templateRegistry.ts |
CLI templates/pages/ |
Page-level templates (e.g. dashboard, settings) |
docsRegistry.ts |
CLI docs/ |
Long-form guide and foundation topics |
blogRegistry.ts |
src/content/blog/posts/ |
Human-authored blog posts (frontmatter validated) |
themeRegistry.ts |
Installed @astryxdesign/theme-* packages |
Built theme objects, keyed by package name |
showcaseRegistry.ts |
Blocks with isShowcase |
Copied showcase source files |
exampleRegistry.ts |
Blocks with exampleFor |
Copied example blocks per component |
The src/generated/ directory is gitignored. Pages import from these registries
and render whatever the pipeline found, with no manual wiring needed.
The Rule
All data comes from the pipeline. Never hardcode package names, component
lists, or theme objects in page code. If you need data about the monorepo,
add it to generate-data.mjs and consume it from a registry.
This means:
- No
import {fooTheme} from '@astryxdesign/theme-foo/built'in page files; usethemeObjectsfrom the generatedthemeRegistry - No hand-maintained arrays of component names; use
componentRegistry - No
if (pkg === '@astryxdesign/core')switches; let the pipeline classify packages
Versioned Content: latest vs canary
The docsite ships one codebase deployed from main, but the data pipeline can
read package docs from two different sources depending on the build target.
The two targets mirror the two npm dist-tags the packages publish under:
| Target | npm dist-tag | Reads package docs from | Deploys |
|---|---|---|---|
latest |
@latest |
the last published npm release | production (astryx.atmeta.com) |
canary |
@canary |
the live monorepo (main, WIP) |
the canary site + every PR preview |
The target is derived from Vercel's VERCEL_ENV: the production deploy is
latest; preview deploys (the main canary site and all PR previews) and local
dev are canary. scripts/resolve-content-root.mjs maps the target to the
filesystem root the pipeline reads from — for latest it downloads the
published package tarballs from npm (their src/ ships the .doc.mjs the
pipeline needs); for canary it reads the live workspace and loads the
component integrations in astryx.config.mjs. Packages marked
astryx.canaryOnly are excluded from the latest snapshot. Their generated
components use the existing isReady: false state and are grouped under the
owning package on canary, with one flask on that package category rather than
one marker per component. Only the documented
data is version-pinned — CLI template demos are live-rendered React and
always resolve @astryxdesign/core from the bundled workspace version.
⚠️ Contributor gotcha: library changes don't show on the production site until they're released. Production (
astryx.atmeta.com) documents the last published release. If you add a component, change a prop, or update docs and merge tomain, those changes will not appear in production until the next release publishes to npm. To see your merged change in a deployed site, use the canary site or any PR preview (both readmain) — or the "Canary docs" link in the footer. The canary banner links back to production.
Local dev is unaffected. pnpm dev has no VERCEL_ENV, so it defaults to
canary and reads the live workspace — your local changes show up as expected.
To preview the latest view locally, run the pipeline with
DOCSITE_TARGET=latest (needs network to fetch the published tarballs).
Adding a New Theme
- Create the theme package under
packages/themes/<name>/ - Add
"@astryxdesign/theme-<name>": "*"toapps/docsite/package.jsondependencies - Add
@import "@astryxdesign/theme-<name>/theme.css"tosrc/app/globals.css - Load the theme's fonts (see below)
- Run
pnpm generate; the theme appears inthemeRegistry.ts,packageRegistry.ts, the sidebar, craft page, and package detail page automatically
Only add public (non-private) theme packages to the docsite.
Font loading
Themes reference fonts by name but don't bundle the font files. If the fonts aren't loaded, the theme silently falls back to system fonts.
The docsite loads all custom typefaces from Google Fonts via a single <link>
tag in src/app/layout.tsx. When adding a new theme, check which fonts it
declares and add any missing families to that URL.
Each theme's own README documents exactly which fonts it needs and how to load
them. Check the theme's ## Fonts section for the specific Google Fonts URL.
Adding a New Package
- Create the package under
packages/<name>/ - Add
"@astryxdesign/<name>": "*"toapps/docsite/package.jsondependencies - For a component package other than Core, add
astryx.integration.mjswithcomponents: './src', include that file (andsrc) in the package'sfiles, and list the package inapps/docsite/astryx.config.mjs. Keep optional showcase blocks in the package too and expose their directory through the integration'stemplatesfield; the docsite retrieves them through the CLI template API. A package that publishes only canaries also setsastryx.canaryOnly: truein itspackage.json. A package that publishes stable releases joins the Changesetsfixedgroup in.changeset/config.jsonso it versions with Core: the production snapshot fetches every documented package at Core's published version, and a stable integration on its own version would fail production builds as a partly published release. - Run
pnpm generate
The package appears in the sidebar, the libraries section, and gets its own
/docs/<name> detail page. If the package contains .doc.mjs files,
its components are extracted into componentRegistry.ts as well. Canary-only
packages and components appear only on canary builds and carry a flask icon.
A configured package that is a stable release (neither private nor
astryx.canaryOnly) is documented on the production site too, from its
published tarball, starting with its first stable release
(scripts/resolve-content-root.mjs).
Adding a Blog Post
The blog lives at /blog and /blog/<slug>. Posts are human-authored Markdown
files with YAML frontmatter under src/content/blog/posts/. Adding a post is
close to dropping in one file — discovery, validation, and sorting are automatic.
See src/content/blog/README.md for the full
guide: frontmatter reference, post types, the author registry, cover images, and
local preview. In short:
- Create
src/content/blog/posts/<slug>.mdwith required frontmatter (title,description,date,type,authors,tags). - If you are a new author, add yourself to
src/content/blog/authors.ts. - Run
pnpm generate && pnpm test && pnpm typecheck, thenpnpm devto preview.
Required frontmatter is validated at build time; drafts (draft: true) are
excluded from production output.
Project Structure
apps/docsite/
├── scripts/
│ └── generate-data.mjs # The data pipeline
├── src/
│ ├── generated/ # gitignored — pipeline output
│ ├── app/
│ │ ├── globals.css # CSS imports (reset, astryx base, theme stylesheets)
│ │ ├── layout.tsx # Root layout
│ │ ├── providers.tsx # Theme + client providers
│ │ ├── (docs)/ # Main docs routes (components, packages, docs)
│ │ ├── blog/ # Blog index + post detail (no sidebar)
│ │ └── craft/ # Craft landing (templates, themes, showcases)
│ ├── components/ # Shared UI components
│ ├── content/blog/ # Blog posts (MD + frontmatter) + authors.ts
│ └── lib/blog/ # Blog discovery, validation, and types
├── package.json
└── .gitignore # Excludes src/generated/
Commands
| Command | What it does |
|---|---|
pnpm generate |
Run the data pipeline |
pnpm dev |
Start Next.js dev server (auto-generates first) |
pnpm build |
Production build (auto-generates first) |
pnpm typecheck |
Run tsc --noEmit |
pnpm test |
Run vitest |
pnpm test:watch |
Run vitest in watch mode |
Playground preview restrictions
The playground is for trying Astryx code, not saving its runtime data.
Production previews (including deployed PR previews) are ephemeral and run
with sandbox="allow-scripts": Docsite origin-bound storage and parent-page DOM
access are unavailable. Local storage may throw; previewed code has no
persistence guarantee. In-memory interaction still works; the AI Chat template's
resizable panel already falls back when its storage is unavailable. Reloading or
replacing the preview resets its runtime state, then restores the editor's current
code, theme, and mode.
Production Chromium tests also characterize these browser consequences of the opaque origin; they do not establish separate playground capability policy:
- Clipboard and microphone: Chromium's permission policy denies clipboard writes and microphone access in the preview. Copy did not report success; readable text can still be selected for manual copying. Dictation remained idle while typing worked.
- Native pickers: cross-origin
showPicker()is restricted for date/time controls; typed entry and Astryx'snativePicker="never"surface remain usable. File and color controls have browser-defined exceptions and can still respond to a user gesture. The sandbox is not a blanket ban on every native picker. - Navigation: previewed Astryx links use native anchors instead of inheriting the docsite's Next router. Fragment links stay in the current document. A non-fragment navigation replaces the document and triggers preview recovery.
next dev retains the original same-origin sandbox so development assets load.
It is not evidence for the production security boundary. Do not add
allow-same-origin to make a production demo work.
Testing
Tests live in src/__tests__/data-extraction.test.ts and validate the generated
registries: package discovery, component extraction, theme wiring, etc. Run
pnpm generate before running tests since they import from src/generated/.
Browser contracts for the playground preview live in e2e/ and run with
pnpm test:docsite-browser from the repo root against a production build
(pnpm build at the root, then pnpm build here); see playwright.config.ts.