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:

Good to know: Running next without a command is an alias for next dev.

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)                              Size     First Load JS
┌ ○ /_not-found                          0 B               0 kB
└ ƒ /products/[id]                       0 B               0 kB
 
○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

• Size: The size of assets downloaded when navigating to the page client-side. The size for each route only includes its dependencies.
• First Load JS: The size of assets downloaded when visiting the page from the server. The amount of JS shared by all is shown as a separate metric.

Both of these values are compressed with gzip. The first load is indicated by green, yellow, or red. Aim for green for performant applications.

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 lint options

Warning: This option is deprecated and will be removed in Next 16. A codemod is available to migrate to ESLint CLI.

next lint runs ESLint for all files in the pages/, app/, components/, lib/, and src/ directories. It also provides a guided setup to install any required dependencies if ESLint is not already configured in your application.

The following options are available for the next lint 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 (default: .next/types):

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

Good to know: next typegen loads your Next.js config (next.config.js, next.config.mjs, or next.config.ts) using the production build phase. Ensure any required environment variables and dependencies are available so the config can load correctly.

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:
  • experimental.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.

Warning: --debug-prerender is for debugging in development only. Do not deploy builds generated with --debug-prerender to production, as it may impact performance.

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

Good to know: PORT cannot be set in .env as booting up the HTTP server happens before any other code is initialized.

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