create-next-app

Purpose

create-next-app is the npm-published CLI that runs when a user types npx create-next-app@latest. It scaffolds a new Next.js project from one of the bundled templates, prompts for options (TypeScript, ESLint, Tailwind, src/, App Router, import alias), installs dependencies, and prints next steps.

Source: packages/create-next-app/. Published under the same name, with its own version line independent of next since it's installed via npx rather than locally.

Directory layout

packages/create-next-app/
├── README.md
├── index.ts          # CLI entry — argv parsing, prompts, dispatch (25 KB)
├── create-app.ts     # The actual app-creation logic (8 KB)
├── helpers/          # Lockfile detection, package manager detection, downloads, validation
├── templates/        # 11 bundled templates (App Router + Pages Router × JS/TS × Tailwind/no-Tailwind, etc.)
└── package.json

Flow

graph TD
    Start[npx create-next-app] --> ParseArgs[parse argv with commander]
    ParseArgs --> Prompt{Interactive?}
    Prompt -- yes --> Ask[prompt for name, TS, ESLint, Tailwind, src/, App, alias]
    Prompt -- no --> Defaults[apply CLI flags]
    Ask --> Resolve
    Defaults --> Resolve[resolve template based on choices]
    Resolve --> Create[create-app.ts]
    Create --> Copy[copy template files]
    Copy --> ConfigPM[detect npm/yarn/pnpm/bun]
    ConfigPM --> Install[install deps]
    Install --> InitGit[git init + first commit]
    InitGit --> Banner[print next steps]

Templates

packages/create-next-app/templates/ holds the source for each scaffold variant. Common templates:

• app/ (App Router, JavaScript)
• app-tw/ (App Router with Tailwind)
• app-empty/ (minimal App Router)
• default/ (Pages Router, JavaScript)
• default-tw/ (Pages Router with Tailwind)
• default-empty/ (minimal Pages Router)
• TypeScript variants of each (-ts/ suffix or sibling directories)

The selector in index.ts matches the user's prompt answers to a directory under templates/.

Helpers

packages/create-next-app/helpers/ contains:

• Package manager detection — figures out whether the user is on npm, yarn, pnpm, or bun based on the invocation chain.
• Validation — project name (must be valid npm package name), directory (must be empty or non-existent).
• Tarball / git fetch — for the --example flag that lets users start from any GitHub repo.
• Lockfile management — copies the right lockfile for the detected PM.

CLI flags

The CLI accepts a long list of flags so it can be used non-interactively. The most common:

Flag	Effect
--ts / --js	TypeScript or JavaScript
--app / --no-app	App Router or Pages Router
--tailwind	Add Tailwind CSS
--eslint	Add ESLint config
--src-dir	Use a src/ directory
--import-alias	Set the @/* import alias path
--use-npm / --use-pnpm / --use-yarn / --use-bun	Force a package manager
--example <url>	Clone an example from any URL or examples/<name> shorthand
--example-path <path>	Sub-path within the example repo
--turbopack	Add the --turbopack flag to scripts (now default)
-y / --yes	Accept all defaults (non-interactive)

How it relates to the rest of the repo

• examples/ — the --example flag can pull any subdirectory of vercel/next.js/examples. The 229-example library doubles as a curated set of starters.
• next — create-next-app writes a package.json that depends on next@latest. It does not depend on a local Next.js workspace at runtime.

Key source files

File	Purpose
packages/create-next-app/index.ts	CLI entry, argv parsing, prompts
packages/create-next-app/create-app.ts	Project creation logic
packages/create-next-app/helpers/	PM detection, validation, downloads
packages/create-next-app/templates/	Template directory tree