# Next.js — User Guide

Next.js is **The React Framework** (per its own `package.json` description) — a full-stack toolchain for building React applications with file-system routing, a production build pipeline, a development server with hot-code reloading, and a first-class command-line interface. This guide covers everything you need to install Next.js, scaffold a project, run the `next` CLI, and configure your application, documented directly from the framework's source code at commit `d3e41fb`.

> [!NOTE]
> This guide was generated from Next.js version **`16.3.0-canary.90`** (the version stamped in `packages/next/package.json` at the documented commit). Command flags and configuration keys reflect that exact source tree. Canary releases move quickly; run `next --version` to confirm what you have installed, and treat options marked *experimental* as subject to change.

---

## 1. Quick Start

The fastest path from nothing to a running Next.js app is the **`create-next-app`** scaffolder, which is published alongside Next.js and pinned to the same version.

```bash
npx create-next-app@latest my-app
cd my-app
npm run dev
```

The dev server starts on port `3000` by default. Open the URL it prints:

```text
  ▲ Next.js 16.3.0
  - Local:        http://localhost:3000
  - Network:      http://0.0.0.0:3000

 ✓ Ready in 1200ms
```

> [!TIP]
> `create-next-app` runs an interactive prompt for any option you don't pass on the command line. To skip the prompts entirely and accept the defaults (TypeScript, Tailwind CSS, App Router), add `--yes`:
> ```bash
> npx create-next-app@latest my-app --yes
> ```

Once the dev server is running, edit `app/page.tsx` (App Router) and the browser updates instantly via Fast Refresh.

---

## 2. Installation

### 2.1 Requirements

| Requirement | Value | Source |
|---|---|---|
| Node.js | **`>=20.9.0`** | `engines.node` in `packages/next/package.json` |
| React | `^18.2.0` or `^19.0.0` | `peerDependencies.react` |
| React DOM | `^18.2.0` or `^19.0.0` | `peerDependencies["react-dom"]` |
| Operating systems | Linux, macOS, Windows | `next info` platform checks (`win32`, `linux`, `darwin`) |

Next.js declares `react` and `react-dom` as **peer dependencies** — they must be present in your project. The `next` binary checks for them on startup and warns if they are missing:

```text
The module 'react' was not found. Next.js requires that you include it in
'dependencies' of your 'package.json'. To add it, run 'npm install react'
```

> [!IMPORTANT]
> Next.js hard-fails if your Node.js version is below the required range. The exact message is:
> ```text
> You are using Node.js 18.19.0. For Next.js, Node.js version ">=20.9.0" is required.
> ```
> Upgrade Node before continuing.

Several capabilities are enabled by **optional** peer/optional dependencies that you install only if you need them:

| Package | Enables | Declared as |
|---|---|---|
| `sharp` (`^0.34.5`) | High-performance image optimization | `optionalDependencies` |
| `sass` (`^1.3.0`) | Sass/SCSS stylesheet support | optional peer |
| `@playwright/test` (`^1.51.1`) | `next experimental-test` runner | optional peer |
| `@opentelemetry/api` (`^1.1.0`) | OpenTelemetry tracing | optional peer |
| `babel-plugin-react-compiler` | React Compiler (`reactCompiler` config) | optional peer |

### 2.2 Scaffolding a new project with `create-next-app`

The recommended install method. It creates the project directory, writes a template, and installs dependencies.

=== "npm"

    ```bash
    npx create-next-app@latest my-app
    ```

=== "pnpm"

    ```bash
    pnpm create next-app my-app
    ```

=== "Yarn"

    ```bash
    yarn create next-app my-app
    ```

=== "Bun"

    ```bash
    bunx create-next-app my-app
    ```

Use the package-manager flags to force a specific installer regardless of how you invoked the command: `--use-npm`, `--use-pnpm`, `--use-yarn`, or `--use-bun`.

### 2.3 Adding Next.js to an existing project

Install the three core packages manually:

```bash
npm install next@latest react@latest react-dom@latest
```

Add the standard scripts to your `package.json` (this is exactly what the scaffolder writes):

```json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}
```

> [!NOTE]
> The `next` binary is registered as `"next": "./dist/bin/next"` in the package's `bin` field, so `npx next`, `pnpm next`, and the npm scripts above all resolve to the same CLI.

---

## 3. Configuration Basics

Next.js reads configuration from a **`next.config`** file at your project root. All four of these forms are supported: `next.config.js`, `next.config.mjs`, `next.config.ts`, and `next.config.mts`.

A minimal config exports an object typed as `NextConfig`:

```javascript
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  // your options here
}

module.exports = nextConfig
```

> [!TIP]
> If you use `next.config.ts` or `next.config.mts`, you can opt into Node.js's native TypeScript resolution by passing `--experimental-next-config-strip-types` to `next dev`, `next build`, or `next start`.

The handful of options most users touch first:

| Option | Default | What it does |
|---|---|---|
| `basePath` | `''` | Serve the app under a sub-path of your domain (e.g. `/docs`). |
| `assetPrefix` | `''` | Point static assets at a CDN origin. |
| `trailingSlash` | `false` | Redirect URLs to/from a trailing slash. |
| `distDir` | `'.next'` | Change the build output directory. |
| `output` | *(unset)* | `'standalone'` for Docker self-hosting, `'export'` for static HTML. |
| `env` | `{}` | Inline environment variables at build time. |
| `images` | *(built-in defaults)* | Configure the Image Optimization component. |

### Environment Variables

Next.js has built-in support for `.env` files and the `env` config key. Two conventions matter for users:

- Variables prefixed with **`NEXT_PUBLIC_`** are inlined into the browser bundle and are readable client-side (e.g. `NEXT_PUBLIC_SANITY_PROJECT_ID`, `NEXT_PUBLIC_SENTRY_DSN`).
- All other variables are server-only and never shipped to the browser.

```bash
# .env.local
DATABASE_URL=postgres://...
NEXT_PUBLIC_API_URL=https://api.example.com
```

The `PORT` environment variable is honored by `next dev`, `next start`, and `next experimental-analyze` as an alternative to the `-p/--port` flag.

> [!CAUTION]
> Never put secrets behind the `NEXT_PUBLIC_` prefix — they will be embedded verbatim in the client JavaScript that every visitor downloads.

For the **complete** configuration reference — every `next.config` key with its default — see the [Admin Guide](/vercel/next.js/admin-guide/).

---

## 4. Everyday Usage

Everything you do day-to-day flows through the **`next`** CLI. Its own description: *"The Next.js CLI allows you to develop, build, start your application, and more."* Global flags:

| Flag | Purpose |
|---|---|
| `-v, --version` | Print the Next.js version. |
| `-h, --help` | Show help. Works on any subcommand. |

> [!NOTE]
> `next dev` is the **default command** — running `next` with no subcommand starts the dev server.

### 4.1 Develop locally — `next dev`

Starts Next.js in development mode with hot-code reloading, error reporting, and the dev overlay.

```bash
next dev
```

```text
  ▲ Next.js 16.3.0 (Turbopack)
  - Local:   http://localhost:3000

 ✓ Ready in 1.1s
```

Common options:

```bash
next dev -p 4000              # custom port (or set PORT=4000)
next dev -H 127.0.0.1         # bind a specific hostname (default 0.0.0.0)
next dev --turbopack          # force the Turbopack bundler
next dev --webpack            # force webpack instead
next dev --experimental-https # serve over HTTPS with a generated self-signed cert
```

> [!TIP]
> `next dev` respects Node's inspector via `--inspect [[host:]port]` so you can debug server-side code. For `next start`/`next build`, prefer `NODE_OPTIONS='--inspect'` instead — passing `--inspect` to non-dev commands is rejected as deprecated.

### 4.2 Build for production — `next build`

Creates an optimized production build. The output reports information about each route.

```bash
next build
```

Useful options:

```bash
next build --turbopack        # build with Turbopack
next build --profile          # enable React production profiling
next build --no-mangling      # disable identifier mangling (debugging only)
next build --experimental-app-only  # build only App Router routes
next build -d                 # verbose build output
```

> [!WARNING]
> `--no-mangling` and `--profile` both print a warning that they affect performance and should be used only for debugging. Don't ship a production build made with them.

### 4.3 Serve the production build — `next start`

Starts Next.js in production mode. **The app must be compiled with `next build` first.**

```bash
next build
next start -p 8080
```

Options: `-p/--port` (default `3000`, or `PORT`), `-H/--hostname` (default `0.0.0.0`), and `--keepAliveTimeout <ms>` to control how long inactive connections stay open.

### 4.4 Inspect your environment — `next info`

Prints system details for bug reports (OS, CPU, memory, Node/npm/Yarn/pnpm versions, and relevant package versions):

```bash
next info
```

```text
Operating System:
  Platform: linux
  Arch: x64
  Available memory (MB): 32000
  Available CPU cores: 8
Binaries:
  Node: 20.11.0
  npm: 10.2.4
Relevant Packages:
  next: 16.3.0-canary.90
  react: 19.0.0
  react-dom: 19.0.0
Next.js Config:
  output: N/A
```

Add `--verbose` to collect deeper diagnostics, including a `next-swc` installation check (helpful for native-binary load failures).

### 4.5 Manage telemetry — `next telemetry`

Next.js collects **completely anonymous** usage telemetry. Enable, disable, or check status:

```bash
next telemetry status
next telemetry disable
next telemetry enable
```

The accepted argument values are `disable`, `enable`, and `status`; the `--enable` and `--disable` flags do the same thing.

### 4.6 Generate route types — `next typegen`

Generates TypeScript definitions for your routes, pages, and layouts **without running a full build**:

```bash
next typegen
```

Use `--webpack` to validate `next.config.js` with webpack during type generation. Pair it with `tsc` in CI: `next typegen && tsc`.

### 4.7 Upgrade Next.js — `next upgrade`

Upgrades a Next.js app to a target version in one command (it delegates to `@next/codemod` to apply codemods):

```bash
next upgrade                      # upgrade to the appropriate dist-tag
next upgrade --revision latest    # or canary / rc / beta / an exact version like 15.0.0
next upgrade --verbose
```

> [!NOTE]
> The default `--revision` is chosen from your installed version: a `-canary.` build defaults to `canary`, `-rc.` to `rc`, `-beta.` to `beta`, otherwise `latest`.

### 4.8 Run tests — `next experimental-test`

An experimental wrapper around a test runner (currently **Playwright**) for `next/experimental/testmode` tests:

```bash
next experimental-test
next experimental-test --test-runner playwright
```

If no Playwright config exists, the first run scaffolds one and tells you to create your first test. This command requires `experimental.testProxy: true` in `next.config`.

---

## 5. Common Workflows

### 5.1 Scaffold a TypeScript + Tailwind App Router project

TypeScript, Tailwind, and the App Router are the scaffolder defaults:

```bash
npx create-next-app@latest my-app
# or explicitly:
npx create-next-app@latest my-app --ts --tailwind --app
```

### 5.2 Scaffold a minimal or JavaScript project

```bash
npx create-next-app@latest my-app --js --empty --no-tailwind
```

`--empty` produces a bare starting point; `--js` selects JavaScript over TypeScript.

### 5.3 Bootstrap from an official example or a GitHub URL

```bash
npx create-next-app@latest my-blog --example blog-starter
npx create-next-app@latest my-app --example https://github.com/user/repo/tree/branch/subdir
```

If the GitHub branch name itself contains a slash, split the path out with `--example-path`.

### 5.4 Build a headless API-only app

```bash
npx create-next-app@latest my-api --api
```

`--api` initializes a headless API using the App Router (no UI templates).

### 5.5 Standard develop → build → serve loop

```bash
npm run dev        # develop with Fast Refresh
npm run build      # produce the optimized .next output
npm run start      # serve the build in production mode
```

### 5.6 Self-host with a standalone build

Set `output: 'standalone'` in `next.config` (or the `NEXT_PRIVATE_STANDALONE` env var), then `next build` emits a `.next/standalone` directory with only the files needed to run:

```javascript
// next.config.js
module.exports = { output: 'standalone' }
```

### 5.7 Produce a fully static export

```javascript
// next.config.js
module.exports = { output: 'export' }
```

`next build` then writes static HTML/CSS/JS to the `out/` directory — no Node.js server required.

> [!IMPORTANT]
> The old `next export` command **no longer exists**. Running it prints:
> ```text
> `next export` has been removed in favor of 'output: export' in next.config.js.
> ```

---

## 6. Advanced Usage

### 6.1 Choosing a bundler: Turbopack vs. webpack vs. Rspack

Next.js ships with **Turbopack** (its Rust bundler) and still supports webpack. Both `next dev` and `next build` accept `--turbopack` and `--webpack` to force one explicitly. `create-next-app --rspack` scaffolds a project configured to use Rspack.

> [!TIP]
> `next build --experimental-analyze` (Turbopack only) is available, and the dedicated `next experimental-analyze` command opens an interactive web UI to inspect your production bundle (default port `4000`, overridable with `--port` or `PORT`).

### 6.2 HTTPS in development

```bash
next dev --experimental-https
```

This generates a self-signed certificate automatically. To use your own, pass the paths:

```bash
next dev --experimental-https \
  --experimental-https-key ./certs/key.pem \
  --experimental-https-cert ./certs/cert.pem \
  --experimental-https-ca ./certs/ca.pem
```

> [!WARNING]
> Self-signed certificates are an experimental feature — the CLI prints "use with caution."

### Plugins & Extensions

- **React Compiler.** Set `reactCompiler: true` (or an options object) in `next.config` to enable the React Compiler, and install the optional `babel-plugin-react-compiler` peer dependency. `create-next-app --react-compiler` scaffolds it on.
- **SWC compiler transforms.** The `compiler` config key enables built-in transforms: `removeConsole`, `reactRemoveProperties`, `styledComponents`, `emotion`, `styledJsx`, `relay`, and compile-time `define`/`defineServer` replacements.
- **Transpiling local/external packages.** `transpilePackages: ['pkg-name']` replaces the old `next-transpile-modules` package.
- **Turbopack loaders.** Configure webpack-compatible loaders and module rules for Turbopack via the top-level `turbopack` config key.

### 6.3 AI coding-agent support

A notable v16 feature: when `next dev` detects an AI coding agent and there's no managed agent-rules block, Next.js auto-generates `AGENTS.md` and `CLAUDE.md` at your project root so the agent reads version-matched docs from `node_modules/next/dist/docs/` instead of stale training data. Disable it with `agentRules: false`. `create-next-app` includes an `AGENTS.md` by default (`--agents-md`).

---

## 7. How It Works

A quick mental model — enough for confident everyday use. Deep architecture lives in the [Admin Guide](/vercel/next.js/admin-guide/).

- **File-system routing.** Files under `app/` (App Router) or `pages/` (Pages Router) become routes automatically. `useFileSystemPublicRoutes` (default `true`) governs this.
- **Two render-time bundlers, one CLI.** Whether you pick Turbopack or webpack, the same `next` commands drive development and production builds.
- **Build output.** `next build` writes to `.next/` by default (`distDir`). `output: 'standalone'` and `output: 'export'` change the shape of what's produced for self-hosting.
- **Dev server as a supervised child process.** `next dev` forks the actual server into a child process, sizing its memory (`--max-old-space-size` defaults to ~50% of system RAM) and automatically restarting it on certain exits. That's why you occasionally see a clean restart mid-session.
- **`page` extensions.** By default Next.js treats `.tsx`, `.ts`, `.jsx`, and `.js` files as routes (`pageExtensions`).
- **Telemetry.** Anonymous and opt-out via `next telemetry disable`.

---

## 8. Troubleshooting

Each item below is grounded in an exact message or behavior from the Next.js source or its issue tracker.

### Error: `You are using Node.js <version>. For Next.js, Node.js version ">=20.9.0" is required.`

**Cause:** Your Node.js runtime is older than the required range in `engines.node`.
**Solution:** Install Node.js `20.9.0` or newer (e.g. via `nvm install 20`).
**Prevention:** Pin your Node version with an `.nvmrc` or the `engines` field in your own `package.json`.

### Error: `The module 'react' was not found.` (or `'react-dom'`)

**Cause:** `react`/`react-dom` are peer dependencies and aren't installed in your project.
**Solution:** `npm install react react-dom`.
**Prevention:** Keep both in your project's `dependencies`, not just `devDependencies`.

### Error: `> No such directory exists as the project root: <dir>`

**Cause:** The directory argument passed to `next dev`/`build`/`start` doesn't exist.
**Solution:** Run the command from your project root, or pass a valid `[directory]` argument.
**Prevention:** Use the npm scripts (`npm run dev`) which run from the package root.

### Error: `` `next export` has been removed in favor of 'output: export' in next.config.js. ``

**Cause:** You ran the removed `next export` command.
**Solution:** Remove the command; set `output: 'export'` in `next.config` and run `next build`. The static site lands in `out/`.
**Prevention:** Update any CI/deploy scripts that still call `next export`.

### Error: `` `--inspect` flag is deprecated. Use env variable NODE_OPTIONS instead ``

**Cause:** You passed `--inspect` to a command other than `dev` or `start`.
**Solution:** Use `NODE_OPTIONS='--inspect' next <command>` instead.
**Prevention:** Reserve `--inspect` for `next dev`/`next start`.

### Warning: `You are running Next.js on an Apple Silicon Mac with Rosetta 2 translation…`

**Cause:** An x86-64 build of Node.js is running under Rosetta on an Apple Silicon Mac, which degrades performance.
**Solution:** Install a native `arm64` build of Node.js.
**Prevention:** Verify with `node -p process.arch` — it should report `arm64`.

### Warning: non-standard `NODE_ENV`

**Cause:** `NODE_ENV` is set to something other than `production`, `development`, or `test`, or is set in a way that conflicts with the command (e.g. `NODE_ENV=development next build`).
**Solution:** Leave `NODE_ENV` unset and let Next.js pick it (`dev` → `development`, all others → `production`), or set only standard values.
**Prevention:** Don't hard-code `NODE_ENV` in your build scripts.

### Warning: `Your project has both 'sass' and 'node-sass' installed…`

**Cause:** Both Sass implementations are present; Next.js expects only one.
**Solution:** Remove `node-sass` — keep `sass`.
**Prevention:** Use the `sass` package (Dart Sass) exclusively.

### Warning: `Your project has '@next/font' installed as a dependency…`

**Cause:** The deprecated `@next/font` package is installed.
**Solution:** Use the built-in `next/font` instead; run the suggested codemod (`npx @next/codemod@latest built-in-next-font .`).
**Prevention:** `@next/font` is slated for removal — migrate now.

### Error: `Catch-all must be the last part of the URL.`

**Cause:** A catch-all route segment (`[...slug]`) appears before other path segments.
**Solution:** Move the catch-all to the end of the route path.
**Prevention:** Follow the App/Pages Router file-naming rules for dynamic and catch-all segments.

### Port already in use / reserved port

**Cause:** The chosen port is occupied or is one Next.js refuses to bind (a reserved/unsafe port).
**Solution:** Pass a different `-p`/`--port` or set `PORT`. When neither `--port` nor `PORT` is specified, `next dev` will automatically retry the next available port.
**Prevention:** Reserve a known-free port in your dev scripts.

### Turbopack build consumes multi-GB memory on Apple Silicon (issue #92055)

**Cause:** `@next/swc-darwin-arm64` can allocate large, slow-to-reclaim memory during Turbopack compilation on Apple Silicon.
**Solution:** Track the upstream issue; as a workaround, try the latest canary and monitor memory. For very large builds, webpack (`--webpack`) may behave differently.
**Prevention:** Keep Next.js updated — Turbopack memory behavior is actively being fixed.

### Standalone output may contain symlinks resolving outside `.next/standalone` on Windows + pnpm (issue #95450)

**Cause:** With `output: 'standalone'` under pnpm on Windows, traced symlinks can point outside the standalone directory.
**Solution:** Verify your `.next/standalone` bundle before shipping; consider a non-symlinked install strategy in your Docker build.
**Prevention:** Test the standalone artifact in the target container.

> [!NOTE]
> For framework-level behavior questions not covered here, `next info` (and `next info --verbose`) produce the exact diagnostics the maintainers ask for when you open an issue.

---

## 9. FAQ

**Q: Which Node.js version do I need?**
Node.js `>=20.9.0`, as declared in `packages/next/package.json`. The CLI refuses to run on older versions.

**Q: Do I have to use TypeScript?**
No. TypeScript is the `create-next-app` default, but `--js`/`--javascript` scaffolds a JavaScript project, and `next.config.js` works fine without TypeScript.

**Q: Turbopack or webpack — which one runs by default?**
You can force either with `--turbopack` or `--webpack` on `next dev` and `next build`. Both bundlers are supported by the same commands.

**Q: How do I change the dev/production port?**
Pass `-p <port>` (e.g. `next dev -p 4000`) or set the `PORT` environment variable. The default is `3000`.

**Q: What happened to `next lint`?**
There is no `next lint` command in this version — the CLI's linting subcommand is not part of the v16 command set. Use ESLint directly, or scaffold ESLint/Biome config with `create-next-app --eslint` / `--biome`.

**Q: How do I deploy without a Node.js server?**
Set `output: 'export'` and run `next build`; the static site is written to `out/`. For a slimmed-down Node.js deploy (e.g. Docker), use `output: 'standalone'`.

**Q: How do I opt out of telemetry?**
Run `next telemetry disable`. Telemetry is completely anonymous and opt-out.

**Q: Can I use a `.ts` config file?**
Yes — `next.config.ts` and `next.config.mts` are supported. Add `--experimental-next-config-strip-types` to use Node's native TypeScript resolution.

**Q: How do I generate route types for CI type-checking?**
`next typegen` writes route type definitions without a full build. Chain it as `next typegen && tsc`.

**Q: What are the `AGENTS.md` and `CLAUDE.md` files that appeared in my project?**
`next dev` auto-generates them when it detects an AI coding agent, so the agent reads version-matched Next.js docs. Disable with `agentRules: false` in `next.config`.

---

## 10. Reference

### CLI Reference

Top-level `next` commands (from `packages/next/src/bin/next.ts`):

| Command | Description |
|---|---|
| `next dev [directory]` | **(default)** Start development mode with hot-code reloading. |
| `next build [directory]` | Create an optimized production build. |
| `next start [directory]` | Start production mode (after `next build`). |
| `next info` | Print system details for bug reports. |
| `next telemetry [disable\|enable\|status]` | Manage anonymous telemetry. |
| `next typegen [directory]` | Generate route/page/layout TypeScript types. |
| `next upgrade [directory]` | Upgrade a Next.js app to a target version. |
| `next experimental-analyze [directory]` | Interactive bundle analyzer web UI (Turbopack only). |
| `next experimental-test [directory] [args…]` | Run `testmode` tests via a test runner (Playwright). |
| `next experimental-request-insights [directory]` | Inspect request insights from a running dev server. |
| `next internal <subcommand>` | Internal debugging commands (not covered by semver). |

> [!NOTE]
> `next export` still exists as a hidden command but only prints a removal message. There is **no** `next lint` command in this version.

**`next dev` options**

| Option | Default | Description |
|---|---|---|
| `-p, --port <port>` | `3000` (env `PORT`) | Port to serve on. |
| `-H, --hostname <hostname>` | `0.0.0.0` | Hostname to bind. |
| `--turbopack` / `--turbo` | — | Use Turbopack. |
| `--webpack` | — | Use webpack. |
| `--inspect [[host:]port]` | — | Enable the Node.js inspector for server code. |
| `--experimental-https` | — | Serve HTTPS with a generated self-signed cert. |
| `--experimental-https-key <path>` | — | Path to an HTTPS key file. |
| `--experimental-https-cert <path>` | — | Path to an HTTPS cert file. |
| `--experimental-https-ca <path>` | — | Path to an HTTPS CA file. |
| `--disable-source-maps` | `false` | Don't start the dev server with source maps. |
| `--no-server-fast-refresh` | — | Disable server-side Fast Refresh. |
| `--experimental-next-config-strip-types` | — | Native TS resolution for `next.config.(ts\|mts)`. |
| `--experimental-cpu-prof` | — | CPU profiling (profiles saved to `.next-profiles/`). |

**`next build` options**

| Option | Default | Description |
|---|---|---|
| `--turbopack` / `--turbo` | — | Build with Turbopack. |
| `--webpack` | — | Build with webpack. |
| `-d, --debug` | — | Verbose build output. |
| `--profile` | — | React production profiling. |
| `--no-mangling` | — | Disable identifier mangling (debugging). |
| `--experimental-app-only` | — | Build only App Router routes. |
| `--experimental-analyze` | — | Analyze bundle output (Turbopack only). |
| `--experimental-build-mode [mode]` | `default` | `compile`, `generate`, or `generate-env`. |
| `--debug-build-paths <patterns>` | — | Comma-separated globs for selective builds. |
| `--experimental-next-config-strip-types` | — | Native TS resolution for `next.config.(ts\|mts)`. |

**`next start` options**

| Option | Default | Description |
|---|---|---|
| `-p, --port <port>` | `3000` (env `PORT`) | Port to serve on. |
| `-H, --hostname <hostname>` | `0.0.0.0` | Hostname to bind. |
| `--keepAliveTimeout <ms>` | — | Max ms before closing inactive connections. |
| `--inspect [[host:]port]` | — | Enable the Node.js inspector. |

**`create-next-app` options**

| Option | Description |
|---|---|
| `--ts, --typescript` | TypeScript project *(default)*. |
| `--js, --javascript` | JavaScript project. |
| `--tailwind` | Tailwind CSS config *(default)*. |
| `--app` | App Router project. |
| `--api` | Headless API using the App Router. |
| `--src-dir` | Put source in a `src/` directory. |
| `--empty` | Bare starting point. |
| `--react-compiler` | Enable React Compiler. |
| `--eslint` | Add ESLint config. |
| `--biome` | Add Biome config. |
| `--rspack` | Enable Rspack as the bundler. |
| `--import-alias <prefix/*>` | Import alias (default `@/*`). |
| `--use-npm` / `--use-pnpm` / `--use-yarn` / `--use-bun` | Force a package manager. |
| `--skip-install` | Skip installing packages. |
| `-e, --example <name\|url>` | Bootstrap from an example or GitHub URL. |
| `--example-path <path>` | Path to the example within the repo. |
| `--agents-md` | Include `AGENTS.md` *(default)*. |
| `--disable-git` | Skip git initialization. |
| `--reset, --reset-preferences` | Reset saved `create-next-app` preferences. |
| `--yes` | Use saved preferences/defaults for unprovided options. |

### Configuration Quick Reference

The user-facing subset of `next.config` options (defaults from `defaultConfig`):

| Key | Default | Purpose |
|---|---|---|
| `distDir` | `'.next'` | Build output directory. |
| `basePath` | `''` | Serve under a sub-path. |
| `assetPrefix` | `''` | CDN origin for assets. |
| `trailingSlash` | `false` | Trailing-slash redirect behavior. |
| `output` | *(unset)* | `'standalone'` or `'export'`. |
| `compress` | `true` | gzip compression. |
| `poweredByHeader` | `true` | Emit the `X-Powered-By` header. |
| `reactStrictMode` | `null` | React Strict Mode. |
| `pageExtensions` | `['tsx','ts','jsx','js']` | Recognized route file extensions. |
| `env` | `{}` | Build-time environment variables. |
| `images` | *(built-in defaults)* | Image Optimization config. |
| `redirects` / `rewrites` / `headers` | *(functions)* | Custom routing rules. |
| `typedRoutes` | `false` | Statically typed links. |
| `reactCompiler` | *(unset)* | Enable React Compiler. |
| `transpilePackages` | *(unset)* | Transpile listed packages. |
| `cacheMaxMemorySize` | `52428800` (50 MB) | In-memory cache size in bytes. |

> [!TIP]
> The full reference — including every `compiler`, `images`, `logging`, and `experimental` key with defaults — is in the [Admin Guide](/vercel/next.js/admin-guide/).

---

_Generated July 2026 from vercel/next.js at d3e41fb. AI-generated documentation. The library is checked by sampling (three repositories so far); this repository was the one sampled in the latest review, which scored its User Guide 55 out of 70 and found 1 factual error in about 30 checked claims. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._