Skip to main content
Never copy an existing member to start a new one. pnpm new picks the right directory, package scope, tier tag and script set, copies the target repo’s LICENSE and formats the result. The shapes it renders are decided in ADR 0126.
Run it with --dry-run first to see what it would write. Then run pnpm install and pnpm verify.

​
Kinds

--category is required for package and must be one of: foundation, application, communication, cross-cutting, data, developer, experience, runtime, security, state. Names are kebab-case. There is no Next.js kind.

​
Flags

Every flag is non-interactive, so agents and CI run pnpm new without a prompt.

​
Tokens

The scaffold replaces these tokens in file contents and path names. Other double-brace text (JSX style objects) is left alone. TITLE and DESCRIPTION are JSON-escaped when written into .json and .jsonc files. Template files hold tokens, so oxfmt and oxlint skip tools/scaffold/templates/**; the generator formats what it renders.

​
What you get

Every member gets package.json, turbo.jsonc with its one tier tag, README.md, AGENTS.md with a ## PII table, CHANGELOG.md and the LICENSE, with code in src/ and tests in __tests__/. A service and a package also get config/<name>.config.ts; a package gets resources/. Every template with code ships a passing test, because the vitest preset fails an empty suite. After scaffolding:
  1. Replace the placeholder README and AGENTS text with the member’s real purpose and its PII table.
  2. pnpm install to link the new member, then pnpm verify.
  3. Add a changeset (pnpm changeset).

​
Changing a template

Edit the template under tools/scaffold/templates/, then run node --test tools/scripts/__tests__/scaffold.test.mjs (or pnpm validate). The test renders every kind into a temporary directory and fails if a token is left in a path or a file, if a rendered .json file does not parse, or if the rendered member fails the validator’s member, service and exports checks. It also covers package entries, the JSON escaping, the target repo’s LICENSE, port allocation and --dry-run. When you add a kind, add a row to the test’s case list and to tools/scaffold/README.md.

​
Moves are scripted, never hand edits

Moving or renaming a file or folder means rewriting every import and link that points at it. Do that with a codemod, not an editor: a script git mvs each path, rewrites every relative specifier and link from the file’s new location, prints what it changed and can run with --dry-run.
Status: target. Stackra has no move codemod yet. Port one before the first large restructuring. Until then, move in small steps, run pnpm typecheck and pnpm verify after each, and never mix a move with a behaviour change in one commit.

​
Checks that back this page

See also Structure, Packages and Definition of done.