SKU under test: aurora-mesh (free tier). Swap the slug if you are verifying another free material. Full repo copy lives in docs/COLD-INSTALL.md.
Prerequisites (not on the clock)
- Node 20+ and a package manager (pnpm / npm / yarn)
- Network access to the Frameline registry host under test (local
http://localhost:3000or production) - A browser (WebGL optional for CSS-only materials;
aurora-meshneeds WebGL)
Timed steps
| # | Action | Pass criteria |
|---|---|---|
| 1 | Scaffold a fresh app: pnpm create next-app@latest cold-install --ts --tailwind --eslint --app --src-dir --use-pnpm. cd cold-install && pnpm install if needed. | App boots with pnpm dev. |
| 2 | Init shadcn if missing: pnpm dlx shadcn@latest init -y (accept defaults that match the app). | components.json exists. |
| 3 | Point @frameline at the registry under test. For local: set registries["@frameline"].url to http://localhost:3000/api/registry/{name}. No auth header for free SKUs. | Registry entry present; no FRAMELINE_REGISTRY_TOKEN required. |
| 4 | Install: pnpm dlx shadcn@latest add @frameline/aurora-mesh or the explicit local registry URL. | Component lands under the configured UI path (e.g. src/components/ui/aurora-mesh.tsx). |
| 5 | Drop the component into src/app/page.tsx (full-bleed decorative layer + sibling content). | Typecheck / save succeeds. |
| 6 | Load http://localhost:3000 in the browser. | Surface renders; no install 403; no missing-module error. |
Stop the clock after step 6. Record elapsed time and registry host used.
Local install one-liner
pnpm dlx shadcn@latest add "http://localhost:3000/api/registry/aurora-mesh"
Failure triage
- 403 — Paid slug or auth wrongly required for free. Use catalog
tier: "free"only. - 404 — Wrong registry URL or slug typo.
- Peer deps — Install packages the registry lists; re-run step 4 if the CLI prompted and you skipped.
- Blank canvas — WebGL blocked or unexpected reduced-motion path; see Troubleshooting.