next build

Build your Next.js application for production with next build.

next build creates an optimized production build of your application. The output shows a summary of each route:

Route (app)
┌ ○ /_not-found
└ ƒ /products/[id]

○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

Usage

next build [directory] [options]

Options

[directory] · string

The directory containing the Next.js application. Defaults to the current working directory.

--turbopack · boolean

Force Turbopack (the default bundler). Also available as --turbo.

--webpack · boolean

Build using Webpack instead of the default Turbopack.

-d / --debug · boolean

Enable verbose build output. Shows rewrites, redirects, and headers configuration.

--profile · boolean

Enable production React profiling. Adds a small overhead.

--no-lint · boolean

Disable linting during the build.

--no-mangling · boolean

Disable name mangling. Reduces performance; use only for debugging.

--experimental-app-only · boolean

Build only App Router routes, skipping Pages Router routes.

--experimental-build-mode [mode] · string · default: "default"

Use an experimental build mode. Choices: 'compile', 'generate', 'default'.

--experimental-analyze · boolean

Analyze bundle output using the bundle explorer. Only compatible with the Turbopack bundler.

--experimental-debug-memory-usage · boolean

Enable memory profiling features to help debug memory consumption during the build.

--experimental-upload-trace <traceUrl> · string

Report a subset of the debugging trace to a remote HTTP URL. Includes sensitive data.

--experimental-next-config-strip-types · boolean

Use Node.js native TypeScript resolution for next.config.ts or next.config.mts.

--debug-prerender · boolean

Debug prerender errors in a development-like build. Do not deploy builds produced with this flag.

--debug-build-paths <patterns> · string

Build only specific routes (comma-separated file paths or globs). Useful for faster targeted debugging.

--experimental-cpu-prof · boolean

Enable CPU profiling via V8’s inspector. Profiles are saved to .next/cpu-profiles/ on process exit.

-h / --help · boolean

Show all available options.

Build output analysis

The build output shows route types and sizes. To analyze bundle composition in detail, use the --experimental-analyze flag with Turbopack:

next build --experimental-analyze

This runs a Turbopack build and opens an interactive bundle explorer in the browser.

Standalone output

To produce a self-contained deployment artifact, set output: 'standalone' in next.config.js:

next.config.js

module.exports = {
  output: 'standalone',
}

After running next build, copy static assets and start the server:

cp -r public .next/standalone/ && cp -r .next/static .next/standalone/.next/
node .next/standalone/server.js

Build traces

Next.js generates .nft.json trace files in .next/ that list all files required by each route. These are used by output: 'standalone' to create a minimal deployment bundle.

Examples

Debug prerender errors

next build --debug-prerender

This disables minification, enables server source maps, and continues past the first prerender error to surface all issues at once.

Do not deploy builds created with --debug-prerender—they may have reduced performance.

Build specific routes

# Single route
next build --debug-build-paths="app/page.tsx"

# Multiple routes
next build --debug-build-paths="app/page.tsx,pages/index.tsx"

# Glob patterns
next build --debug-build-paths="app/**/page.tsx"

CPU profiling

next build --experimental-cpu-prof

For Turbopack builds, profiles are named:

• build-main-* — main orchestration process
• build-turbopack-* — Turbopack compilation worker

For Webpack builds:

• build-main-* — main orchestration process
• build-webpack-client-* — client bundle worker
• build-webpack-server-* — server bundle worker
• build-webpack-edge-server-* — edge runtime worker

Version history

Version	Changes
v16.0.0	Turbopack is the default bundler; JS bundle size metrics removed from output
v15.5.0	Turbopack build support in beta
v15.4.0	--debug-prerender flag added