Docs · Guide

Repository

One repo, two packages: the astro-ui component library lives at the root, this docs site lives inweb/ — linked as npm workspaces, built and tested together with Turborepo.

Layout

astro-ui/                   # repo root = the published package
  src/components/         # .astro sources, grouped by category
  src/styles/             # tokens.css (theming API) + base
  src/utils/              # cn(), toast()
  index.ts                # root entry (+ subpath export per component)
  tests/                  # contract + unit suites
  docs/                   # contributor docs (conventions, principles, ADRs)
  web/                    # docs website workspace (Astro app)
    src/pages/            # guides, component catalog, blocks
    src/lib/registry/     # per-component docs metadata + snippets
    src/components/docs/  # live demo renderers
    src/content/          # generated docs (scripts/gen-docs.ts)
    tests/                # consistency + snippet suites
    scripts/              # gen-docs, render audits, id checks
  package.json            # workspaces: ["web"], turbo pipelines
  turbo.json              # build/test/lint/check tasks
  .github/workflows/      # CI installs once, then runs every pipeline

Library ↔ site link

The root package.json declares"workspaces": ["web"], so one install links everything and the demo always renders the working copy — no publish step while developing components. Pages that need library files (changelog, token source) resolve them through the shared src/lib/ui-path.ts helper, which finds the package via its workspace link or a standalonenode_modules install alike.

npm install          # once, at the root
npm test             # library suites, then web suites
npm run build        # docs site production build (turbo-cached)

Workflows

npm run dev      # docs site with live components (turbo persistent)
npm test         # vitest (library) + turbo web suites
npm run check    # astro check (library) + turbo web check
npm run lint     # biome + eslint (library; web has no lint config)
npm run build    # turbo web build (css + check + astro build)

Turborepo caches task outputs, so repeatedbuild/test runs only redo what changed. CI (see .github/workflows/ci.yml) runs install once, then lint, check, tests, and the docs build.