Skip to main content

Getting Started

Standing up a new client project usually means an afternoon of copy-pasting auth, config, and CI from whatever repo is closest at hand. next-starters turns two production-grade Next.js starter templates into a running app in one command instead. This page covers prerequisites, the quickstart, what happens under the hood, and how to pull in additional capabilities via skills.

Prerequisites​

  • Node.js >= 22 — the CLI and its scaffolders run on modern Node. (The root package.json engines field currently reads >=20 for historical reasons, but the skill-publishing pipeline requires 22.11+, so 22 is the version actually tested against.)
  • pnpm — every template and the root CLI use pnpm exclusively; no npm/yarn lockfiles are supported.
  • git — for the git-symlink skill-install channel described below.

Quickstart​

# Marketing site for a new client
node bin/create-client.mjs acme-salon \
  --template marketing \
  --out ../acme/02-repos/acme-salon

# SaaS dashboard, with Stripe billing on
node bin/create-client.mjs acme-ops \
  --template dashboard \
  --out ../acme/02-repos/acme-ops \
  --enable billing

Then:

cd <out> && pnpm install && pnpm dev

What happens on a scaffold​

  1. The CLI reads templates/<name>/template.config.json, which declares every __TOKEN__ placeholder the template uses (brand name, colors, fonts, URLs) and any opt-in modules.
  2. Unless you pass --yes or --set, it prompts for each token. Prompt defaults resolve template default < remembered answer from a prior run < --set/--enable — answers are persisted per template in ~/.config/next-starters/answers.json, so repeat scaffolds barely need typing.
  3. It copies the template (excluding node_modules, .next, .git, .turbo, dist), literal-replaces every token across all text files and paths, drops template.config.json from the output, and writes a scaffold.json recording the choices actually made.
  4. If --env was passed, it copies each .env.example to a sibling .env (skipping any that already exist) — values are placeholders, fill in real secrets before running.
  5. postScaffold commands run (currently just pnpm install), and the new project is ready at --out.

Installing skills​

Skills are reusable, documented capabilities (auth flows, env config, testing patterns, MCP tooling, and more) that extend a scaffolded project or this repo itself. There are three ways to pull one in:

  1. Git-symlink (works today, no publishing required): 
    skills add git@github.com:catesandrew/next-starters.git --skill skills/<name> -g
  2. npm package — every skill is also published as @next-starters/skill-<name>, installable with any standard npm-compatible client.
  3. Claude Code plugin marketplace — install all 22 skills at once as a single plugin, directly inside Claude Code: 
    /plugin marketplace add catesandrew/next-starters
    /plugin install ns@next-starters
    See Installing via the plugin marketplace for the full walkthrough (verifying, updating, non-interactive/cloud sessions).

See the Skills Catalog for the full list, one-line descriptions, and use cases for all 22 skills.

Next steps​

  • Architecture — the story behind the two templates and the shared house style.
  • CLI Reference — every flag for create-client.mjs and the other scaffolders.