Scale Stack

Flat-packed, production-shaped Next.js — assembled in one command.

Most starters give you a repo that compiles on day one. Scale Stack gives you the wiring teams usually add over weeks: strict TypeScript, typed env, shadcn/Tailwind, safe actions, Docker, agent rules, and optional fittings (ORM, auth, AI chat, API client, CI, i18n, utility libs) — selected once at scaffold time, then owned by your team.

Fire-and-forget by design: init runs once. Upgrades are normal dependency and config work.

Quick start

Interactive (recommended when you are at a terminal):

npx scale-stack init my-app

Headless (CI, agents, scripts — pass every feature explicitly; see For agents & CI):

# Minimal baseline — no ORM, auth, chat, CI, or analytics
npx scale-stack init my-app -y

# Common team stack (includes utility-libs — recommended for most apps)
npx scale-stack init my-app --orm --auth --chat --utility-libs --ci github -y

# Everything implemented
npx scale-stack init my-app \
  --orm --auth --chat fullstack --api-client fullstack \
  --i18n --utility-libs --ci github --analytics plausible --pre-commit -y

Requirements: Node 22+, pnpm on PATH. Creates ./<name>/ under the current directory and runs pnpm install inside it.

Why it feels different

• Speed — runnable app in minutes, not weeks of lint/env/Docker/auth/agent wiring.
• Standardization — same colocation-first layout, pinned tooling, and AGENTS.md baseline everywhere.
• Quality — strict config, safe server actions, observability stubs, and Agent Skills from the first commit.
• AI-native — generated projects ship AGENTS.md, MCP wiring, and per-feature agent guidance for the stack you actually picked.

Tip: add --utility-libs on most scaffolds — Motion, date-fns, es-toolkit, useHooks, and ts-pattern plus matching Agent Skills, with almost no config overhead.

In every project

These are always on, regardless of flags:

| Layer | What you get | | ------------------- | ----------------------------------------------------------------------------------- | | App | Next.js 16 App Router, strict TypeScript, colocation-first structure | | Env | Typed, validated env (src/env.ts + env.example) composed from feature fragments | | UI | shadcn/ui + Tailwind, shared layout, loading/error boundaries | | State & actions | Client state, type-safe server actions, form handling | | Tooling | ESLint + Prettier, pinned deps, Docker/Compose for selected local services | | Agent-native | AGENTS.md, Agent Skills, per-feature integration notes |

Opt-in features layer on top via the interactive picker or CLI flags.

Commands

scale-stack init [name]

Assembles a new project. Interactive when stdin/stdout is a TTY and -y is not passed. Headless when -y is passed or output is non-TTY — in headless mode, absent flags mean disabled (not “pick the interactive default”).

Core stack

| Flag | Effect | | --------------------------------------------- | ----------------------------------------------------------------------------- | | --name <name> | Project name (overrides positional [name]) | | --orm | Prisma ORM (PostgreSQL) | | --auth | Better Auth — stateful sessions with --orm, stateless JWT without | | --chat [client-only\|fullstack\|none] | AI chat (AI SDK + AI Elements). Bare --chat → client-only; omit → no chat | | --api-client [client-only\|fullstack\|none] | hey-api OpenAPI client. Bare --api-client → fullstack; omit → none | | --api-spec <source> | OpenAPI spec URL or file path (default: Swagger Petstore v3) |

Providers

| Flag | Effect | | ---------------------------------------- | --------------------------------------------------------------------------------------- | | --ci [github\|circleci\|none] | Bare --ci → GitHub Actions; omit → none. CircleCI accepted but skipped (coming soon) | | --analytics [plausible\|posthog\|none] | Bare --analytics → Plausible; omit → none. PostHog accepted but skipped (coming soon) |

Smart-Fittings

| Flag | Effect | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | --i18n | next-intl locale routing and <LocaleSwitcher> | | --utility-libs | Recommended default — Motion, date-fns, es-toolkit, useHooks, ts-pattern + Agent Skills; steers agents toward project-standard libs | | --pre-commit | prek hooks for lint, format, typecheck |

Coming soon (accepted, ignored)

--jobs (Inngest), --a11y (accessibility tooling)

General

| Flag | Effect | | ----------- | --------------------------------------------------------------------------- | | -y, --yes | Skip prompts (required for headless). Does not enable features you omit |

Run npx scale-stack init --help for the full flag list.

For agents & CI

Headless contract (short version):

1. Use -y and pass explicit flags for every feature you want. -y alone scaffolds the minimal baseline only.
2. Provider flags (--ci, --analytics, --chat, --api-client): bare flag → catalog default; absent → none.
3. Boolean flags (--orm, --auth, --i18n, --utility-libs, …): present → on; absent → off. Prefer --utility-libs on any non-minimal scaffold.
4. On success: cd <name>, copy env.example → .env, fill vars required by your flags (see skill reference).
5. Non-zero exit = generation or pnpm install failed; check stderr and .scale-stack/generate.log in the output project.

Full spec for Claude skills and automation: .agents/skills/scale-stack-init/SKILL.md — decision tree, recipes, flag matrix, env handoff, and version pinning for reproducible runs.

Maintainers

pnpm install
pnpm lint
pnpm test
pnpm build
pnpm test:e2e
npm pack --dry-run

pnpm test:e2e builds the CLI, runs the init matrix in temp dirs, and verifies each project with pnpm install && pnpm build.

Demo

Standalone HTML slideshow: demo/showcase.html — open demo/showcase.html.