create-next-app CLI Flags

Complete reference for every create-next-app command-line flag in Next.js 15, when to use each one, and copy-paste commands for common scenarios. Sourced from the bundled docs in next/dist/docs/01-app/03-api-reference/06-cli/create-next-app.md.

Recipe

Quick-reference recipe card - copy-paste ready.

# The "everything on" command - TypeScript, Tailwind, App Router,
# src/ directory, custom alias, explicit npm, Turbopack, non-interactive
npx create-next-app@latest my-app \
  --typescript \
  --tailwind \
  --app \
  --src-dir \
  --import-alias "@/*" \
  --use-npm \
  --turbopack

When to reach for this: Anytime you want a reproducible, non-interactive scaffolding command in a README, a bootstrap script, or a CI job.

Working Example

All flags (Next.js 15)

Scenario commands

# Minimal - TS and App Router, nothing else
npx create-next-app@latest my-app \
  --typescript --app \
  --no-tailwind --no-eslint --no-src-dir
 
# With Tailwind v4 (this cookbook's stack)
npx create-next-app@latest my-app \
  --typescript --tailwind --app \
  --import-alias "@/*"
 
# With a src/ directory (common in larger codebases)
npx create-next-app@latest my-app \
  --typescript --tailwind --app --src-dir
 
# Yes to all current defaults, skip every prompt
npx create-next-app@latest my-app --yes
 
# Skip every prompt and install, useful for CI
npx create-next-app@latest my-app --yes --skip-install --disable-git
 
# Bootstrap from an official example
npx create-next-app@latest my-blog --example blog-starter
 
# Bootstrap from any public GitHub repo
npx create-next-app@latest my-app \
  --example "https://github.com/vercel/next.js/tree/canary/examples/with-stripe-typescript"
 
# API-only project (route handlers, no app pages)
npx create-next-app@latest my-api --typescript --api
 
# React Compiler enabled from day one
npx create-next-app@latest my-app \
  --typescript --tailwind --app --react-compiler

Deep Dive

How It Works

create-next-app is a standalone scaffolder published to npm. When you run it through npx, pnpm create, yarn create, or bun create, the package manager downloads the package to a temporary cache and runs its bin entry. The CLI:

1. Parses flags and merges them with any stored preferences under ~/.config/create-next-app/.
2. Prompts only for answers that were not provided on the command line.
3. Picks a template - the default template, --empty for a bare-bones one, or the repo pointed to by -e / --example.
4. Copies files into the target directory, rewriting package names.
5. Runs the chosen package manager's install command unless --skip-install is set.
6. Runs git init and an initial commit unless --disable-git is set.
7. Writes AGENTS.md and CLAUDE.md unless --no-agents-md is set.

Because stored preferences are respected, two developers running the same create-next-app command can get different scaffolds. --reset-preferences or passing every flag explicitly guarantees determinism.

Variations

• Interactive mode: omit every flag - npx create-next-app@latest - and answer prompts one by one. Good for learners; bad for scripts.
• Pin the CLI version: npx create-next-app@15.0.0 my-app ... so your scaffold is reproducible months later.
• Skip git: --disable-git. Useful when scaffolding into an existing monorepo.
• Skip install: --skip-install. You can then edit package.json before running the installer yourself.
• Official example: --example blog-starter. See the examples/ folder in the vercel/next.js repo for the full list.
• GitHub URL example: --example "https://github.com/owner/repo/tree/branch/path". Combine with --example-path if the example lives deep inside a monorepo.

TypeScript Notes

The --typescript and --ts flags are aliases for the exact same behavior - they both write tsconfig.json with strict: true, moduleResolution: "bundler", the Next plugin registered, and @/* paths configured. Everything else is identical.

Compared to adding TypeScript manually later (npm install -D typescript @types/react @types/node, then running next dev), the flag saves one step: Next generates tsconfig.json automatically on first next dev anyway, but the flag also installs the dev dependencies and writes next-env.d.ts up front. For monorepos where you already control a shared tsconfig.base.json, skipping --typescript and wiring TS yourself is sometimes cleaner.

Gotchas

1. --tailwind vs --no-tailwind - there is no --no-ts-style symmetry for every flag. Most flags support --no-*, but the help text is the source of truth; always check with create-next-app --help.
2. -e means --example, not --eslint. The short flags are compressed and easy to mistype. Use long flags in scripts.
3. -ts is not a short flag - --ts requires two dashes. A single-dash -ts will be parsed as -t -s and error.
4. Defaults move between Next.js versions. Tailwind, ESLint, and Turbopack all became defaults relatively recently. If your README says npx create-next-app@latest, the resulting scaffold will drift over time; pin to @15 or pass every flag explicitly.
5. --use-npm does not block other package managers. It selects npm as the installer for the scaffold step; you can still pnpm install afterwards in the project and it will work (you will just have both lockfiles to clean up).
6. Interactive mode remembers previous answers. A second run in the same shell may silently pre-fill answers from the cache. Use --reset-preferences or --yes plus explicit flags for reproducibility.
7. --yes follows whatever the current defaults are. A CI job using --yes will produce different output after a Next.js major release. Prefer explicit flags in CI.
8. --example disables most other flags. When you bootstrap from an example, flags like --tailwind or --src-dir are ignored because the example already defines its own structure.

Alternatives

FAQs

Quick review of this page - click to expand.

Related

• Basic Next.js Setup
• Next.js + Tailwind v4 + shadcn/ui

External Related Links

• nextjs.org/docs - official Next.js docs
• Next.js API Reference - App Router API reference
• react.dev - official React docs (Learn + full API reference)