next CLI

The Next.js CLI allows you to develop, build, start your application, and more.

Basic usage:

npx next [command] [options]

Reference

The following options are available:

Commands

The following commands are available:

next dev options

next dev starts the application in development mode with Hot Module Reloading (HMR), error reporting, and more. The following options are available when running next dev:

next build options

next build creates an optimized production build of your application. The output displays information about each route. For example:

Route (app)
┌ ○ /_not-found
└ ƒ /products/[id]
 
○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

The following options are available for the next build command:

next start options

next start starts the application in production mode. The application should be compiled with next build first.

The following options are available for the next start command:

next info options

next info prints relevant details about the current system which can be used to report Next.js bugs when opening a GitHub issue. This information includes Operating System platform/arch/version, Binaries (Node.js, npm, Yarn, pnpm), package versions (next, react, react-dom), and more.

The output should look like this:

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 23.6.0
  Available memory (MB): 65536
  Available CPU cores: 10
Binaries:
  Node: 20.12.0
  npm: 10.5.0
  Yarn: 1.22.19
  pnpm: 9.6.0
Relevant Packages:
  next: 15.0.0-canary.115 // Latest available version is detected (15.0.0-canary.115).
  eslint-config-next: 14.2.5
  react: 19.0.0-rc
  react-dom: 19.0.0
  typescript: 5.5.4
Next.js Config:
  output: N/A

The following options are available for the next info command:

next telemetry options

Next.js collects completely anonymous telemetry data about general usage. Participation in this anonymous program is optional, and you can opt-out if you prefer not to share information.

The following options are available for the next telemetry command:

Learn more about Telemetry.

next typegen Options

next typegen generates TypeScript definitions for your application's routes without performing a full build. This is useful for IDE autocomplete and CI type-checking of route usage.

Previously, route types were only generated during next dev or next build, which meant running tsc --noEmit directly wouldn't validate your route types. Now you can generate types independently and validate them externally:

# Generate route types first, then validate with TypeScript
next typegen && tsc --noEmit
 
# Or in CI workflows for type checking without building
next typegen && npm run type-check

The following options are available for the next typegen command:

Output files are written to <distDir>/types (typically: .next/dev/types or .next/types, see isolatedDevBuild):

next typegen
# or for a specific app
next typegen ./apps/web

Additionally, next typegen generates a next-env.d.ts file. We recommend adding next-env.d.ts to your .gitignore file.

The next-env.d.ts file is included into your tsconfig.json file, to make Next.js types available to your project.

To ensure next-env.d.ts is present before type-checking run next typegen. The commands next dev and next build also generate the next-env.d.ts file, but it is often undesirable to run these just to type-check, for example in CI/CD environments.

Examples

Debugging prerender errors

If you encounter prerendering errors during next build, you can pass the --debug-prerender flag to get more detailed output:

next build --debug-prerender

This enables several experimental options to make debugging easier:

• Disables server code minification:
  • experimental.serverMinification = false
  • experimental.turbopackMinify = false
• Generates source maps for server bundles:
  • experimental.serverSourceMaps = true
• Enables source map consumption in child processes used for prerendering:
  • enablePrerenderSourceMaps = true
• Continues building even after the first prerender error, so you can see all issues at once:
  • experimental.prerenderEarlyExit = false

This helps surface more readable stack traces and code frames in the build output.

Building specific routes

You can build only specific routes in the App and Pages Routers using the --debug-build-paths option. This is useful for faster debugging when working with large applications. The --debug-build-paths option accepts comma-separated file paths and supports glob patterns:

# Build a specific route
next build --debug-build-paths="app/page.tsx"
 
# Build more than one route
next build --debug-build-paths="app/page.tsx,pages/index.tsx"
 
# Use glob patterns
next build --debug-build-paths="app/**/page.tsx"
next build --debug-build-paths="pages/*.tsx"

Changing the default port

By default, Next.js uses http://localhost:3000 during development and with next start. The default port can be changed with the -p option, like so:

next dev -p 4000

Or using the PORT environment variable:

PORT=4000 next dev

Using HTTPS during development

For certain use cases like webhooks or authentication, you can use HTTPS to have a secure environment on localhost. Next.js can generate a self-signed certificate with next dev using the --experimental-https flag:

next dev --experimental-https

With the generated certificate, the Next.js development server will exist at https://localhost:3000. The default port 3000 is used unless a port is specified with -p, --port, or PORT.

You can also provide a custom certificate and key with --experimental-https-key and --experimental-https-cert. Optionally, you can provide a custom CA certificate with --experimental-https-ca as well.

next dev --experimental-https --experimental-https-key ./certificates/localhost-key.pem --experimental-https-cert ./certificates/localhost.pem

next dev --experimental-https is only intended for development and creates a locally trusted certificate with mkcert. In production, use properly issued certificates from trusted authorities.

Configuring a timeout for downstream proxies

When deploying Next.js behind a downstream proxy (e.g. a load-balancer like AWS ELB/ALB), it's important to configure Next's underlying HTTP server with keep-alive timeouts that are larger than the downstream proxy's timeouts. Otherwise, once a keep-alive timeout is reached for a given TCP connection, Node.js will immediately terminate that connection without notifying the downstream proxy. This results in a proxy error whenever it attempts to reuse a connection that Node.js has already terminated.

To configure the timeout values for the production Next.js server, pass --keepAliveTimeout (in milliseconds) to next start, like so:

next start --keepAliveTimeout 70000

Passing Node.js arguments

You can pass any node arguments to next commands. For example:

NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next