next CLI

Core Idea

The Next.js CLI drives development, build, start, and diagnostics for a Next.js app; every command is invoked as next <command> [options] via npm/pnpm/yarn/bun.

Key Concepts

• next dev: Starts development mode with HMR; outputs to .next/dev (separate from .next/build), letting dev and build run concurrently.
• next build: Creates the optimized production build and prints a route table (○ static, ƒ dynamic).
• next start: Runs the compiled production server; requires next build first.
• next info: Prints OS/binary/package version info for bug reports.
• next telemetry: Enables/disables Next.js's anonymous telemetry collection.
• next typegen: Generates TypeScript route definitions without a full build, for CI type-checking (next typegen && tsc --noEmit).
• next upgrade: Upgrades the Next.js app to latest, canary, or a specific version.
• next experimental-analyze: Analyzes bundle output via Turbopack (no build artifacts produced); serves an interactive analyzer or writes static files with --output.
• --debug-prerender: Build flag that disables server minification, enables server source maps, and continues past the first prerender error for readable stack traces (dev debugging only, never ship it).
• --debug-build-paths: Builds only matching routes (comma-separated, glob, ! to exclude) for faster iteration on large apps.
• --experimental-cpu-prof: Captures V8 CPU profiles to .next-profiles/ for dev, build, and start.

Code Examples

# Run only specific routes through the build
next build --debug-build-paths="app/**/page.tsx,!app/admin/**"

# Custom port via flag or env var
next dev -p 4000
PORT=4000 next dev

# Self-signed HTTPS for local dev
next dev --experimental-https

# Keep-alive timeout tuning behind a proxy/load balancer
next start --keepAliveTimeout 70000

• O que demonstra: flags mais usados em debugging local, build seletivo e deploy atrás de proxy.

Reference Tables

Command	Purpose
dev	Dev server with HMR
build	Production build + route report
start	Production server (needs prior build)
info	System/version diagnostics
telemetry	Toggle anonymous telemetry
typegen	Generate route types without full build
upgrade	Upgrade Next.js version
experimental-analyze	Bundle composition analysis (Turbopack)

next dev flag	Effect
--turbopack / --turbo	Force Turbopack (default)
--webpack	Use Webpack instead
-p, --port	Port (default 3000, env PORT)
-H, --hostname	Bind hostname (default 0.0.0.0)
--experimental-https[-key/-cert/-ca]	Local HTTPS with mkcert-generated cert

next build flag	Effect
--turbopack / --webpack	Bundler choice
-d, --debug	Verbose output (rewrites/redirects/headers)
--profile	React production profiling
--no-mangling	Disable name mangling (debug only)
--debug-prerender	Verbose prerender error debugging
--debug-build-paths	Build only matching routes

Anti-patterns

• Deploying with --debug-prerender: disables minification and source-map stripping meant for local diagnosis; hurts production performance.
• Setting PORT in .env: the HTTP server boots before .env loads, so it has no effect; pass PORT as a shell env var or use -p.

Key Takeaways

1. next dev/next build output to different directories (.next/dev vs .next), so they can run side by side.
2. Turbopack is enabled by default; --webpack is the explicit opt-out for both dev and build.
3. next typegen decouples route type generation from a full build, useful in CI type-check steps.
4. next upgrade also refreshes the docs bundled in node_modules/next/dist/docs/, keeping AI coding agents current.
5. --debug-build-paths and --debug-prerender are the two main levers for fast, targeted build debugging on large apps.

Connects To

• ch284 turbopack-1: --turbopack/--webpack flags and the bundler this CLI defaults to.
• ch287 installation-1: create-next-app prompts and package.json scripts that call these CLI commands.