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.

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:

  ▲ 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:

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

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:

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:

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:

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

npx create-next-app@latest my-app

pnpm

pnpm create next-app my-app

Yarn

yarn create next-app my-app

Bun

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:

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

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

{
  "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:

// 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:

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.

# .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.

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:

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.

next dev

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

 ✓ Ready in 1.1s

Common options:

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.

next build

Useful options:

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.

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):

next info

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:

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:

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):

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:

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:

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

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

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

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

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:

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

5.7 Produce a fully static export

// 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:

`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

next dev --experimental-https

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

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.

• 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):

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

next build options

next start options

create-next-app options

Configuration Quick Reference

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

Tip

The full reference — including every compiler, images, logging, and experimental key with defaults — is in the Admin Guide.