---
title: "Quick Start"
description: "Next.js provides a robust command-line interface and tooling ecosystem designed to streamline project initialization, template configuration, development server bootstrapping, and diagnostic inspec..."
last_updated: "2026-09-23T10:52:03.136804+00:00"
canonical_url: "https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/getting-started/quick-start"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [packages/create-next-app/index.ts](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts)
- [packages/create-next-app/templates/index.ts](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts)
- [packages/next/src/bin/next.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/bin/next.ts)
- [packages/create-next-app/create-app.ts](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts)
- [packages/next/taskfile.js](https://github.com/blade47/next.js/blob/main/packages/next/taskfile.js)
- [packages/create-next-app/templates/default/js/pages/index.js](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default/js/pages/index.js)
- [run-evals.js](https://github.com/blade47/next.js/blob/main/run-evals.js)
- [packages/create-next-app/templates/default-tw/js/pages/index.js](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-tw/js/pages/index.js)
- [package.json](https://github.com/blade47/next.js/blob/main/package.json)
- [packages/create-next-app/helpers/examples.ts](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts)
- [packages/next-codemod/bin/next-codemod.ts](https://github.com/blade47/next.js/blob/main/packages/next-codemod/bin/next-codemod.ts)
- [packages/create-next-app/templates/app/js/app/page.js](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app/js/app/page.js)
- [packages/create-next-app/templates/default-empty/js/pages/index.js](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-empty/js/pages/index.js)
- [packages/create-next-app/templates/default-tw-empty/js/pages/index.js](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-tw-empty/js/pages/index.js)
- [packages/create-next-app/templates/app-empty/js/app/page.js](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-empty/js/app/page.js)
- [packages/create-next-app/templates/app-tw/js/app/page.js](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-tw/js/app/page.js)
- [packages/create-next-app/templates/default/ts/pages/index.tsx](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default/ts/pages/index.tsx)
- [run-tests.js](https://github.com/blade47/next.js/blob/main/run-tests.js)
- [packages/create-next-app/templates/app-tw-empty/js/app/page.js](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-tw-empty/js/app/page.js)
- [packages/next/src/cli/next-info.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts)
- [packages/next/package.json](https://github.com/blade47/next.js/blob/main/packages/next/package.json)
- [packages/next/app.js](https://github.com/blade47/next.js/blob/main/packages/next/app.js)
- [packages/create-next-app/templates/default-tw/ts/pages/index.tsx](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-tw/ts/pages/index.tsx)
- [packages/create-next-app/package.json](https://github.com/blade47/next.js/blob/main/packages/create-next-app/package.json)
- [packages/create-next-app/templates/default-empty/ts/pages/index.tsx](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-empty/ts/pages/index.tsx)
- [packages/create-next-app/templates/app/ts/app/page.tsx](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app/ts/app/page.tsx)
- [packages/create-next-app/templates/default-tw-empty/ts/pages/index.tsx](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-tw-empty/ts/pages/index.tsx)
- [packages/next/src/client/next-dev.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/client/next-dev.ts)
- [packages/next/src/cli/next-dev.ts](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-dev.ts)
</details>

## Overview

Next.js provides a robust command-line interface and tooling ecosystem designed to streamline project initialization, template configuration, development server bootstrapping, and diagnostic inspection. This infrastructure addresses common friction points during application setup by automating directory scaffolding, fetching remote examples, validating runtime environments, and orchestrating build and test workflows across various architectural and styling preferences.

Sources: [packages/create-next-app/index.ts:41-114](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L41-L114), [packages/create-next-app/create-app.ts:28-66](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L28-L66), [packages/next/src/bin/next.ts:138-155](https://github.com/blade47/next.js/blob/main/packages/next/src/bin/next.ts#L138-L155), [packages/next/src/cli/next-dev.ts:45-63](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-dev.ts#L45-L63), [packages/next/src/cli/next-info.ts:270-329](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L270-L329)

## CLI Scaffolding Entry Points

### CLI Scaffolding Entry Points

The `create-next-app` package initiates execution through a Node.js shebang header (`#!/usr/bin/env node`) located at the root of `packages/create-next-app/index.ts`. It registers process signal listeners (`SIGINT` and `SIGTERM`) executing `handleSigTerm` to immediately terminate the process upon interruption.

Sources: [packages/create-next-app/index.ts:1-26](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L1-L26)

### Prompt State Management and Lifecycle

User interactions via the `prompts` library are managed through `onPromptState`. If a user aborts prompt entry (`state.aborted`), the state handler explicitly restores the terminal cursor by writing escape codes (`\x1B[?25h`), prints a newline, and exits with code `1`.

Sources: [packages/create-next-app/index.ts:27-39](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L27-L39)

> [!WARNING]
> Abruptly terminating prompts without restoring the terminal state leaves the cursor hidden. The `onPromptState` function specifically writes `\x1B[?25h` to prevent terminal lockups on cancellation.
> 
> Sources: [packages/create-next-app/index.ts:27-39](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L27-L39)

### Commander CLI Flag Configuration

The command-line parser relies on `commander` instantiated with `packageJson.name`. It accepts an optional `[directory]` positional argument and supports a comprehensive flag matrix for project customization.

| Option Flag | Type / Argument | Description | Sources |
| :--- | :--- | :--- | :--- |
| `-v, --version` | None | Output the current version of `create-next-app`. | [packages/create-next-app/index.ts:42-46](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L42-L46) |
| `-h, --help` | None | Display help message. | [packages/create-next-app/index.ts:49-49](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L49-L49) |
| `--ts, --typescript` | None | Initialize as a TypeScript project. (default) | [packages/create-next-app/index.ts:50-50](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L50-L50) |
| `--js, --javascript` | None | Initialize as a JavaScript project. | [packages/create-next-app/index.ts:51-51](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L51-L51) |
| `--tailwind` | None | Initialize with Tailwind CSS config. (default) | [packages/create-next-app/index.ts:52-52](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L52-L52) |
| `--react-compiler` | None | Initialize with React Compiler enabled. | [packages/create-next-app/index.ts:53-53](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L53-L53) |
| `--eslint` | None | Initialize with ESLint config. | [packages/create-next-app/index.ts:54-54](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L54-L54) |
| `--biome` | None | Initialize with Biome config. | [packages/create-next-app/index.ts:55-55](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L55-L55) |
| `--app` | None | Initialize as an App Router project. | [packages/create-next-app/index.ts:56-56](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L56-L56) |
| `--src-dir` | None | Initialize inside a `src/` directory. | [packages/create-next-app/index.ts:57-57](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L57-L57) |
| `--rspack` | None | Enable Rspack as the bundler. | [packages/create-next-app/index.ts:58-58](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L58-L58) |
| `--import-alias` | `refix/*>` | Specify import alias to use (default `@/*`). | [packages/create-next-app/index.ts:59-62](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L59-L62) |
| `--api` | None | Initialize a headless API using the App Router. | [packages/create-next-app/index.ts:63-63](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L63-L63) |
| `--empty` | None | Initialize an empty project. | [packages/create-next-app/index.ts:64-64](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L64-L64) |
| `--use-npm` | None | Bootstrap the application using npm. | [packages/create-next-app/index.ts:66-68](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L66-L68) |
| `--use-pnpm` | None | Bootstrap the application using pnpm. | [packages/create-next-app/index.ts:69-72](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L69-L72) |
| `--use-yarn` | None | Bootstrap the application using Yarn. | [packages/create-next-app/index.ts:73-76](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L73-L76) |
| `--use-bun` | None | Bootstrap the application using Bun. | [packages/create-next-app/index.ts:77-80](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L77-L80) |
| `--reset, --reset-preferences` | None | Reset saved preferences for `create-next-app`. | [packages/create-next-app/index.ts:81-84](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L81-L84) |
| `--skip-install` | None | Skip installing packages. | [packages/create-next-app/index.ts:85-88](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L85-L88) |
| `--yes` | None | Use saved preferences or defaults for unprovided options. | [packages/create-next-app/index.ts:89-89](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L89-L89) |
| `-e, --example` | `<example-name\|github-url>` | Bootstrap with an official example or public GitHub URL. | [packages/create-next-app/index.ts:90-98](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L90-L98) |
| `--example-path` | `ath-to-example>` | Specify subdirectory path for complex GitHub examples. | [packages/create-next-app/index.ts:99-108](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L99-L108) |
| `--agents-md` | None | Include AGENTS.md for coding agents. (default) | [packages/create-next-app/index.ts:109-112](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L109-L112) |
| `--disable-git` | None | Skip initializing a git repository. | [packages/create-next-app/index.ts:113-113](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L113-L113) |

Sources: [packages/create-next-app/index.ts:41-113](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L41-L113)

### Argument Parsing and Package Manager Resolution

Commander action handlers parse the positional argument, screening out negated options (`--no-`) which can inadvertently pass into the name argument due to parser constraints. Package manager resolution evaluates explicit CLI options in order (`--use-npm`, `--use-pnpm`, `--use-yarn`, `--use-bun`) or falls back to `getPkgManager()`.

Sources: [packages/create-next-app/index.ts:114-137](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L114-L137)

| Design Choice | Benefit | Cost | Sources |
| :--- | :--- | :--- | :--- |
| Explicit flag overrides (`--use-npm`, etc.) | Direct control over package runner without environment detection heuristics | Verbose CLI surface area requiring maintenance for each runner | [packages/create-next-app/index.ts:66-80](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L66-L80), [packages/create-next-app/index.ts:128-136](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L128-L136) |
| Negated option filtering via `!name.startsWith('--no-')` | Prevents parser misinterpretation of boolean flag toggles as project directory paths | Requires manual string inspection inside action handlers | [packages/create-next-app/index.ts:115-121](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L115-L121) |
| Persistent preferences via `Conf` | Remembers user configuration defaults across executions | Requires disk I/O and state clearance handling (`--reset`) | [packages/create-next-app/index.ts:5-5](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L5-L5), [packages/create-next-app/index.ts:81-84](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L81-L84), [packages/create-next-app/index.ts:139-139](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L139-L139) |

Sources: [packages/create-next-app/index.ts:5-5](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L5-L5), [packages/create-next-app/index.ts:66-84](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L66-L84), [packages/create-next-app/index.ts:115-139](https://github.com/blade47/next.js/blob/main/packages/create-next-app/index.ts#L115-L139)

## Project Generation and Example Extraction

### Overview

The project generation and example extraction workflow coordinates filesystem validation, target directory creation, remote GitHub repository or example tarball streaming, and dependency installation. Driven by the `createApp` function, this subsystem takes the parsed configuration options from the CLI entry point, verifies write permissions and folder emptiness, and delegates to helper utilities to pull template or example sources.

Sources: [packages/create-next-app/create-app.ts:28-66](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L28-L66)

### Application Generation Workflow

The main generation entry point follows a strict call-chain execution walkthrough to validate and construct the project workspace:

`createApp()` → `isWriteable()` → `mkdirSync()` → `isFolderEmpty()` → `getRepoInfo()` / `hasRepo()` / `existsInRepo()` → `downloadAndExtractRepo()` / `downloadAndExtractExample()` → `install()`

1. **Validation and Environment Checks**: `createApp` normalizes the root path using `resolve(appPath)` and checks directory writability via `isWriteable(dirname(root))` [packages/create-next-app/create-app.ts:134-136](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L134-L136). If the parent directory is not writeable, it exits with an error [packages/create-next-app/create-app.ts:136-144](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L136-L144).
2. **Directory Initialization**: Creates the target folder recursively via `mkdirSync(root, { recursive: true })` and inspects whether the folder is empty using `isFolderEmpty(root, appName)` [packages/create-next-app/create-app.ts:148-151](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L148-L151).
3. **Example and Repository Resolution**: If an `--example` flag is provided, `createApp` parses the value as a URL or a built-in example name [packages/create-next-app/create-app.ts:71-83](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L71-L83). When a GitHub URL is supplied, `getRepoInfo` extracts the username, repository name, branch, and file path [packages/create-next-app/helpers/examples.ts:23-62](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L23-L62), followed by `hasRepo()` to verify `package.json` existence via GitHub contents API HEAD requests [packages/create-next-app/create-app.ts:106-115](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L106-L115), [packages/create-next-app/helpers/examples.ts:64-74](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L64-L74). For non-URL example names, `existsInRepo()` verifies availability against `vercel/next.js` examples [packages/create-next-app/helpers/examples.ts:76-87](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L76-L87).
4. **Archive Download and Extraction**: Process changes directory to `root` via `process.chdir(root)` [packages/create-next-app/create-app.ts:160-160](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L160-L160). Depending on whether a custom repo or standard example was specified, `downloadAndExtractRepo` or `downloadAndExtractExample` fetches the tarball stream from `codeload.github.com` and pipes it through the `tar` package extractor (`x`) with up to 3 retries via `async-retry` [packages/create-next-app/create-app.ts:178-191](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L178-L191).
5. **Post-Extraction Asset Copying and Installation**: Copies missing `.gitignore` template files and `next-env.d.ts` for TypeScript projects [packages/create-next-app/create-app.ts:204-220](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L204-L220). If `skipInstall` is false and `package.json` exists, `install(packageManager, isOnline)` runs package installation [packages/create-next-app/create-app.ts:222-227](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L222-L227).

Sources: [packages/create-next-app/create-app.ts:71-227](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L71-L227), [packages/create-next-app/helpers/examples.ts:23-87](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L23-L87), [packages/create-next-app/helpers/examples.ts:99-147](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L99-L147)

> [!NOTE]
> During tarball extraction via `downloadAndExtractRepo`, the helper dynamically determines `rootPath` from the first segment of the POSIX-converted paths inside the archive (`pathSegments[0]`). This avoids breaking the file filter if a GitHub repository has been renamed while the fetch URL was redirected.

Sources: [packages/create-next-app/helpers/examples.ts:111-127](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L111-L127)

### Remote Repository and Example Helper Functions

The example and repository helper module (`packages/create-next-app/helpers/examples.ts`) exports core utilities for fetching and validating remote templates over HTTP.

| Function Name | Parameters | Return Type | Purpose | Sources |
| :--- | :--- | :--- | :--- | :--- |
| `isUrlOk` | `url: string` | `Promise<boolean>` | Checks if a URL responds with HTTP status 200 via a `HEAD` request. | [packages/create-next-app/helpers/examples.ts:14-21](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L14-L21) |
| `getRepoInfo` | `url: URL, examplePath?: string` | `Promise<RepoInfo \| undefined>` | Parses GitHub repository path segments to extract username, repo name, branch, and file path. | [packages/create-next-app/helpers/examples.ts:23-62](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L23-L62) |
| `hasRepo` | `RepoInfo` | `Promise<boolean>` | Validates existence of `package.json` in a remote GitHub repository branch using the contents API. | [packages/create-next-app/helpers/examples.ts:64-74](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L64-L74) |
| `existsInRepo` | `nameOrUrl: string` | `Promise<boolean>` | Verifies if an example exists within `vercel/next.js` examples or via direct URL check. | [packages/create-next-app/helpers/examples.ts:76-87](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L76-L87) |
| `downloadAndExtractRepo` | `root: string, RepoInfo` | `Promise<void>` | Downloads tarball from `codeload.github.com` and extracts target subdirectory contents into `root`. | [packages/create-next-app/helpers/examples.ts:99-130](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L99-L130) |
| `downloadAndExtractExample` | `root: string, name: string` | `Promise<void>` | Downloads the official `vercel/next.js` canary tarball and extracts the specified example folder. | [packages/create-next-app/helpers/examples.ts:132-147](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L132-L147) |

Sources: [packages/create-next-app/helpers/examples.ts:14-147](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L14-L147)

### Design Trade-Offs

| Design Choice | Benefit | Cost | Sources |
| :--- | :--- | :--- | :--- |
| Streaming Tarball Extraction via `node:stream/promises` (`pipeline`) | Avoids writing large archive files to disk; processes archives on the fly | Requires careful filter mapping for Windows vs POSIX path separators | [packages/create-next-app/helpers/examples.ts:4-4](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L4-L4), [packages/create-next-app/helpers/examples.ts:89-147](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L89-L147) |
| Automatic retry wrapper (`async-retry` with 3 retries) | Resiliency against intermittent network blips during remote tarball downloads | Increases total latency when downloading from dead or unresponsive endpoints | [packages/create-next-app/create-app.ts:2-2](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L2-L2), [packages/create-next-app/create-app.ts:178-181](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L178-L181), [packages/create-next-app/create-app.ts:188-190](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L188-L190) |
| Dynamic `rootPath` detection from tar stream | Handles renamed GitHub repositories seamlessly without breaking extraction filters | Adds runtime introspection logic inside the tar filter callback | [packages/create-next-app/helpers/examples.ts:115-122](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L115-L122) |

Sources: [packages/create-next-app/create-app.ts:2-2](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L2-L2), [packages/create-next-app/create-app.ts:178-190](https://github.com/blade47/next.js/blob/main/packages/create-next-app/create-app.ts#L178-L190), [packages/create-next-app/helpers/examples.ts:4-4](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L4-L4), [packages/create-next-app/helpers/examples.ts:89-147](https://github.com/blade47/next.js/blob/main/packages/create-next-app/helpers/examples.ts#L89-L147)

## Starter Template Matrix and Layouts

### Overview

The `create-next-app` package provides structured starter templates that span different routing architectures, languages, and styling engines. The installation routine defined in `packages/create-next-app/templates/index.ts` handles copying these templates, writing configuration overrides for bundlers like Rspack, configuring the React Compiler, rewriting TypeScript or JavaScript path aliases (`@/*`), and organizing files into an optional `src/` directory.

Sources: [packages/create-next-app/templates/index.ts:48-211](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L48-L211)

### Template Layout Matrix

The project templates provide permutations across the App Router and Pages Router, JavaScript and TypeScript, and Tailwind CSS variants alongside empty starter setups.

| Template / Layout Identifier | Router Architecture | Primary Entry File (JS) | Primary Entry File (TS) | Styling & Font Configuration | Sources |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `default` | Pages Router | `pages/index.js` | `pages/index.tsx` | CSS Modules (`Home.module.css`), Google Fonts (`Geist`, `Geist_Mono`) | [packages/create-next-app/templates/default/js/pages/index.js:1-88](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default/js/pages/index.js#L1-L88), [packages/create-next-app/templates/default/ts/pages/index.tsx:1-89](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default/ts/pages/index.tsx#L1-L89) |
| `default-tw` | Pages Router | `pages/index.js` | `pages/index.tsx` | Tailwind CSS utility classes, Google Fonts (`Geist`, `Geist_Mono`) | [packages/create-next-app/templates/default-tw/js/pages/index.js:1-78](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-tw/js/pages/index.js#L1-L78), [packages/create-next-app/templates/default-tw/ts/pages/index.tsx:1-79](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-tw/ts/pages/index.tsx#L1-L79) |
| `default-empty` | Pages Router | `pages/index.js` | `pages/index.tsx` | Minimal Head and basic `Hello world!` markup | [packages/create-next-app/templates/default-empty/js/pages/index.js:1-16](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-empty/js/pages/index.js#L1-L16), [packages/create-next-app/templates/default-empty/ts/pages/index.tsx:1-16](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-empty/ts/pages/index.tsx#L1-L16) |
| `default-tw-empty` | Pages Router | `pages/index.js` | `pages/index.tsx` | Minimal Head with Tailwind / basic markup | [packages/create-next-app/templates/default-tw-empty/js/pages/index.js:1-16](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-tw-empty/js/pages/index.js#L1-L16), [packages/create-next-app/templates/default-tw-empty/ts/pages/index.tsx:1-16](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-tw-empty/ts/pages/index.tsx#L1-L16) |
| `app` | App Router | `app/page.js` | `app/page.tsx` | CSS Modules (`page.module.css`), Next/Image assets | [packages/create-next-app/templates/app/js/app/page.js:1-66](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app/js/app/page.js#L1-L66), [packages/create-next-app/templates/app/ts/app/page.tsx:1-66](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app/ts/app/page.tsx#L1-L66) |
| `app-tw` | App Router | `app/page.js` | `app/page.tsx` | Tailwind CSS utility layout, Next/Image assets | [packages/create-next-app/templates/app-tw/js/app/page.js:1-65](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-tw/js/app/page.js#L1-L65) |
| `app-empty` | App Router | `app/page.js` | `app/page.tsx` | Minimal `Hello World!` main element | [packages/create-next-app/templates/app-empty/js/app/page.js:1-7](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-empty/js/app/page.js#L1-L7) |
| `app-tw-empty` | App Router | `app/page.js` | `app/page.tsx` | Minimal `Hello world!` main element | [packages/create-next-app/templates/app-tw-empty/js/app/page.js:1-7](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-tw-empty/js/app/page.js#L1-L7) |

Sources: [packages/create-next-app/templates/index.ts:43-110](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L43-L110), [packages/create-next-app/templates/default/js/pages/index.js:1-88](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default/js/pages/index.js#L1-L88), [packages/create-next-app/templates/default-tw/js/pages/index.js:1-78](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-tw/js/pages/index.js#L1-L78), [packages/create-next-app/templates/app/js/app/page.js:1-66](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app/js/app/page.js#L1-L66), [packages/create-next-app/templates/default-empty/js/pages/index.js:1-16](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default-empty/js/pages/index.js#L1-L16), [packages/create-next-app/templates/app-empty/js/app/page.js:1-7](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-empty/js/app/page.js#L1-L7), [packages/create-next-app/templates/app-tw/js/app/page.js:1-65](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-tw/js/app/page.js#L1-L65), [packages/create-next-app/templates/default/ts/pages/index.tsx:1-89](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/default/ts/pages/index.tsx#L1-L89), [packages/create-next-app/templates/app-tw-empty/js/app/page.js:1-7](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app-tw-empty/js/app/page.js#L1-L7), [packages/create-next-app/templates/app/ts/app/page.tsx:1-66](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/app/ts/app/page.tsx#L1-L66)

### Template Installation and Directory Structuring Walkthrough

When installing a template, `installTemplate` executes an ordered sequence of file operations and configuration updates:

1. `copy()` — Copies matching glob patterns (`**`) from `packages/create-next-app/templates/[template]/[mode]` into `root`, omitting disabled config files (`!eslint.config.mjs`, `!biome.json`, `!postcss.config.mjs`) and renaming `gitignore` to `.gitignore` and `README-template.md` to `README.md`.
2. Bundler injection (`bundler === Bundler.Rspack`) — Reads `next.config.mjs` or `next.config.ts` and wraps `export default nextConfig;` with `withRspack(nextConfig)`.
3. React Compiler injection (`reactCompiler`) — Inserts `reactCompiler: true,` under `/* config options here */` in the Next config file.
4. Path alias configuration — Updates `tsconfig.json` or `jsconfig.json` compiler options to map path aliases (`@/*` or custom `importAlias`) to `./src/*` if `srcDir` is enabled.
5. `src/` migration (`srcDir`) — Creates the `src` directory via `fs.mkdir` and moves the standard directory names (`app`, `pages`, `styles` defined in `SRC_DIR_NAMES`) into `src/`, subsequently updating entry file references in `src/app/page` or `src/pages/index`.

Sources: [packages/create-next-app/templates/index.ts:43-211](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L43-L211)

> [!NOTE]
> During template installation, `SRC_DIR_NAMES` explicitly restricts source directory relocation to `app`, `pages`, and `styles`. Any other top-level files or folders in the template remain at the project root.
> 
> Sources: [packages/create-next-app/templates/index.ts:43-43](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L43-L43), [packages/create-next-app/templates/index.ts:179-191](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L179-L191)

### Design Trade-Offs

| Design Choice | Benefit | Cost | Sources |
| :--- | :--- | :--- | :--- |
| Conditional exclusion globbing (`!eslint.config.mjs`, `!postcss.config.mjs`) | Prevents unselected linters or CSS tooling config files from polluting generated directories | Requires explicit negation filters for every optional configuration file in the copier call | [packages/create-next-app/templates/index.ts:72-76](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L72-L76) |
| Post-copy text string replacement for Rspack and React Compiler | Avoids heavy Abstract Syntax Tree (AST) parsing dependencies when modifying configuration files | Fragile against custom formatting or non-standard exports in generated configuration files | [packages/create-next-app/templates/index.ts:97-125](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L97-L125) |
| Concurrency-controlled file rewriting via `Sema(8)` for custom import aliases | Prevents EMFILE file descriptor exhaustion errors on large repository trees | Adds synchronization overhead when traversing and rewriting project files | [packages/create-next-app/templates/index.ts:142-177](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L142-L177) |

Sources: [packages/create-next-app/templates/index.ts:72-76](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L72-L76), [packages/create-next-app/templates/index.ts:97-125](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L97-L125), [packages/create-next-app/templates/index.ts:142-177](https://github.com/blade47/next.js/blob/main/packages/create-next-app/templates/index.ts#L142-L177)

## Development Server Startup Flow

### Overview

The development server startup flow orchestrates the lifecycle from the initial Next.js binary invocation through environmental preflight validation, forked server child process creation, and client runtime bootstrapping. 
Sources: [packages/next/src/bin/next.ts:1-120](https://github.com/blade47/next.js/blob/main/packages/next/src/bin/next.ts#L1-L120), [packages/next/src/cli/next-dev.ts:204-521](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-dev.ts#L204-L521), [packages/next/src/client/next-dev.ts:1-25](https://github.com/blade47/next.js/blob/main/packages/next/src/client/next-dev.ts#L1-L25)

### Binary Invocation and Preflight Validation Walkthrough

When executing the Next.js CLI binary, execution proceeds through an explicit validation and hooking pipeline:

1. `require('../server/require-hook')` — Registers runtime module resolution hooks before importing core utilities.
2. Node Version Check — Validates `process.versions.node` against `process.env.__NEXT_REQUIRED_NODE_VERSION_RANGE` using `semver.satisfies`; exits with code `1` if unsupported.
3. Dependency Verification — Resolves `react` and `react-dom` via `require.resolve()`, emitting console warnings if missing from project dependencies.
4. `NextRootCommand.createCommand()` preAction Hook — Sets `NODE_ENV` (defaulting to `'development'` for `dev` and `'production'` otherwise), enforces standard environment checks, pins `process.env.NEXT_RUNTIME = 'nodejs'`, and checks for Apple Silicon Rosetta 2 translation mismatches.
5. `nextDev()` execution (`packages/next/src/cli/next-dev.ts`) — Parses bundler arguments via `parseBundlerArgs`, resolves the project directory via `getProjectDir()`, verifies project directory existence via `fileExists()`, and performs dependency preflight checks.

Sources: [packages/next/src/bin/next.ts:3-116](https://github.com/blade47/next.js/blob/main/packages/next/src/bin/next.ts#L3-L116), [packages/next/src/cli/next-dev.ts:211-262](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-dev.ts#L211-L262)

> [!WARNING]
> If a project contains both `sass` and `node-sass` installed concurrently, the preflight checker emits a warning recommending removal of `node-sass`. Additionally, if `@next/font` is detected in dependencies, a migration warning advising migration to built-in `next/font` is triggered.
> 
> Sources: [packages/next/src/cli/next-dev.ts:231-260](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-dev.ts#L231-L260)

### Dev Server Initialization and Child Process Forking

The `nextDev` function initializes configuration options, inspect addresses, and memory thresholds before spawning the background worker process:

```typescript
      child = fork(startServerPath, {
        stdio: 'inherit',
        execArgv,
        env: {
          ...defaultEnv,
          ...(isTurbopack ? { TURBOPACK: process.env.TURBOPACK } : undefined),
          __NEXT_DEV_SERVER: '1',
          NEXT_PRIVATE_START_TIME: process.env.NEXT_PRIVATE_START_TIME,
          NEXT_PRIVATE_WORKER: '1',
          NEXT_PRIVATE_TRACE_ID: traceId,
          NEXT_PRIVATE_ENABLED_FEATURES: JSON.stringify(enabledFeatures),
          NEXT_PRIVATE_DEV_SPAN_ATTRS: JSON.stringify(devSpanAttrs),
          NODE_OPTIONS: formattedNodeOptions,
          WATCHPACK_WATCHER_LIMIT:
            os.platform() === 'darwin' ? '20' : undefined,
        },
      })
```
Sources: [packages/next/src/cli/next-dev.ts:394-427](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-dev.ts#L394-L427)

| Configuration Option | Default Source / Fallback | Purpose | Sources |
| :--- | :--- | :--- | :--- |
| `max-old-space-size` | 50% of total system memory (`os.totalmem()`) | Overrides Node.js heap limit unless `NEXT_DISABLE_MEM_OVERRIDE` is set | [packages/next/src/cli/next-dev.ts:355-365](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-dev.ts#L355-L365) |
| `WATCHPACK_WATCHER_LIMIT` | `'20'` on macOS (`darwin`), undefined elsewhere | Mitigates Node.js file watcher performance degradation on macOS | [packages/next/src/cli/next-dev.ts:413-414](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-dev.ts#L413-L414) |
| `__NEXT_DEV_SERVER` | `'1'` | Signals to the child process that it runs under development server mode | [packages/next/src/cli/next-dev.ts:400-400](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-dev.ts#L400-L400) |
| `NEXT_PRIVATE_WORKER` | `'1'` | Identifies the child process as an isolated worker instance | [packages/next/src/cli/next-dev.ts:402-402](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-dev.ts#L402-L402) |

Sources: [packages/next/src/cli/next-dev.ts:355-365](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-dev.ts#L355-L365), [packages/next/src/cli/next-dev.ts:400-414](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-dev.ts#L400-L414)

### Client Runtime Bootstrapping

Once the development server compiles and serves client assets, the browser runtime bootstraps by initializing the development hot module replacement client and mounting window bindings:

```typescript
import './register-deployment-id-global'
import './webpack'
import { initialize, version, router, emitter } from './'
import initHMR from './dev/hot-middleware-client'
import { pageBootstrap } from './page-bootstrap'

window.next = {
  version,
  get router() {
    return router
  },
  emitter,
}

const devClient = initHMR()
initialize({ devClient })
  .then(({ assetPrefix }) => {
    return pageBootstrap(assetPrefix)
  })
  .catch((err) => {
    console.error('Error was not caught', err)
  })
```
Sources: [packages/next/src/client/next-dev.ts:1-25](https://github.com/blade47/next.js/blob/main/packages/next/src/client/next-dev.ts#L1-L25)

> [!NOTE]
> `window.next.router` is defined using a getter property to maintain live bindings since the router instance is initialized asynchronously after client module evaluation.
> 
> Sources: [packages/next/src/client/next-dev.ts:8-15](https://github.com/blade47/next.js/blob/main/packages/next/src/client/next-dev.ts#L8-L15)

## Environment Diagnostics and Version Inspection

### Overview

Next.js provides built-in environment diagnostics and version inspection capabilities through diagnostic command-line utilities and codemod tooling. The system inspects host system details, compiler bindings, binary dependencies, and package configurations to diagnose runtime environment health.
Sources: [packages/next/src/cli/next-info.ts:254-330](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L254-L330), [packages/next-codemod/bin/next-codemod.ts:1-25](https://github.com/blade47/next-codemod/bin/next-codemod.ts#L1-L25)

### Host System and Installation Diagnostics

The verbose diagnostics routine evaluates platform compatibility, checking for `win32`, `linux`, or `darwin` platforms. It queries system wrappers to report Windows Subsystem for Linux (WSL) status, Docker containerization, continuous integration (CI) environment presence, binary toolchain versions, and relevant package versions.
Sources: [packages/next/src/cli/next-info.ts:254-330](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L254-L330)

| Diagnostic Category | Checked Metric | Source / Implementation Detail | Sources |
| :--- | :--- | :--- | :--- |
| Host System | WSL, Docker, CI | `isWsl`, `isDocker()`, `ciInfo.isCI` | [packages/next/src/cli/next-info.ts:282-292](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L282-L292) |
| Binaries | Node, npm, Yarn, pnpm | `process.versions.node`, binary path execution | [packages/next/src/cli/next-info.ts:310-313](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L310-L313) |
| Relevant Packages | next, eslint-config-next, react, react-dom, typescript | `getPackageVersion()` utility lookup | [packages/next/src/cli/next-info.ts:315-319](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L315-L319) |
| Configuration | output configuration | `nextConfig.output` property | [packages/next/src/cli/next-info.ts:321-321](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L321-L321) |

Sources: [packages/next/src/cli/next-info.ts:282-321](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L282-L321)

> [!NOTE]
> Node.js diagnostic reports are automatically retrieved via `process.report?.getReport()`. Sensitive fields including `cwd`, `commandLine`, `host`, `cpus`, and `networkInterfaces` are explicitly deleted prior to output rendering to prevent leaking host secrets.
> 
> Sources: [packages/next/src/cli/next-info.ts:335-352](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L335-L352)

### SWC Binding Verification and Fallback Resolution

Verification of `next-swc` inspects compiled native binaries by loading bindings and querying the target architecture triple. 
Sources: [packages/next/src/cli/next-info.ts:367-387](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L367-L387)

The inspection call-chain executes as follows:
`loadBindings()` → retrieves WASM binary preference from `nextConfig.experimental?.useWasmBinary` → evaluates `bindings.getTargetTriple()` → verifies successful target string return to confirm native binding integrity.
Sources: [packages/next/src/cli/next-info.ts:374-386](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L374-L386)

If primary loading fails, the diagnostic tool iterates through platform architecture triples using `@napi-rs/triples`, verifying optional dependencies and fallback directories:
Sources: [packages/next/src/cli/next-info.ts:392-411](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L392-L411)

```typescript
          for (const triple of triples) {
            const triplePkgName = `@next/swc-${triple.platformArchABI}`
            if (tryResolve(triplePkgName)) {
              break
            }

            if (!fallbackBindingsDirectory) {
              continue
            }

            tryResolve(path.join(fallbackBindingsDirectory, triplePkgName))
```
Sources: [packages/next/src/cli/next-info.ts:446-459](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.ts#L446-L459)

> [!CAUTION]
> If all target triples fail resolution and fallback checks, `next-swc` diagnostics report a failure state, indicating that native compilation acceleration is unavailable on the host architecture.
> 
> Sources: [packages/next/src/cli/next-info.ts:396-401](https://github.com/blade47/next.js/blob/main/packages/next/src/cli/next-info.

## Related

- [System Overview](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/getting-started/system-overview)
- [CLI Commands](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/technical/build-and-config/cli-commands)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/8f4009b0-65bd-4480-9b00-e201f0914bb3/llms.txt) for all pages in this wiki.