Composition

Scaffolding

Generate a project containing only the surfaces you asked for.

scripts/scaffold.mjs reads the manifests in composition/ and writes a new project directory: the shell, the chosen surfaces, the union of the slices those surfaces require, a generated package.json and a filtered .env.example.

Usage

Bash

node scripts/scaffold.mjs --surfaces docs --out ../my-docs --name my-docs
node scripts/scaffold.mjs --surfaces landing,docs --out ../my-site
node scripts/scaffold.mjs --surfaces landing,dashboard --out ../my-app

--surfaces — comma-separated surface ids. Required.
--out — output directory. Required.
--slices — capability slices no surface requires, such as billing. See Billing.
--name — package name for the generated project.
--url — the site's canonical URL.
--targets — platforms beyond the web; mobile adds iOS and Android shells, desktop adds macOS, Windows and Linux ones. See Mobile apps and Desktop apps.
--app-id — the bundle id for mobile and desktop.
--dry-run — print the resolved plan and exit without writing.
--json — machine-readable output.
--force — overwrite an existing output directory.

Inspect before you write

--dry-run --json prints the resolved plan: the surfaces, the slices pulled in through requires, every file that would be copied, the merged dependency list and the environment variables. It is the fastest way to confirm that a composition really excludes what you think it does.

Bash

node scripts/scaffold.mjs --surfaces docs --out ../tmp --dry-run --json

What the generated project contains

Dependencies are the shell's plus the chosen slices' — nothing else. A docs project has no @supabase/ssr and no @upstash/redis entry, so npm install never fetches them. Run it clean to prove the composition is real:

Bash

cd ../my-docs
npm install
npm run build

Installing from the generated package.json rather than reusing the template's node_modules is deliberate: an undeclared dependency fails immediately instead of resolving by accident.

Adding a surface

Create the route group under src/app/.
Add composition/surfaces/<id>.json listing its files and requires.
If the shell references the surface, add absentTransforms with exact anchors so the references are removed when the surface is left out.
Scaffold both with and without it, and build both.

Step four is the whole point. A surface that has never been scaffolded without is a surface whose independence is a guess.

Last updated August 27, 2026

Edit this page on GitHub