Skip to content

next CLI

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

Basic usage:

Terminal
npm run next [command] [options]

Reference

The following options are available:

OptionsDescription
-h or --helpShows all available options
-v or --versionOutputs the Next.js version number

Commands

The following commands are available:

CommandDescription
devStarts Next.js in development mode with Hot Module Reloading, error reporting, and more.
buildCreates an optimized production build of your application. Displaying information about each route.
startStarts Next.js in production mode. The application should be compiled with next build first.
infoPrints relevant details about the current system which can be used to report Next.js bugs.
lintRuns ESLint for all files in the /src, /app, /pages, /components, and /lib directories. It also provides a guided setup to install any required dependencies if ESLint it is not already configured in your application.
telemetryAllows you to enable or disable Next.js' completely anonymous telemetry collection.

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:

OptionDescription
-h, --helpShow all available options.
[directory]A directory in which to build the application. If not provided, current directory is used.
--turboStarts development mode using Turbopack.
-p or --port <port>Specify a port number on which to start the application. Default: 3000, env: PORT
-Hor --hostname <hostname>Specify a hostname on which to start the application. Useful for making the application available for other devices on the network. Default: 0.0.0.0
--experimental-httpsStarts the server with HTTPS and generates a self-signed certificate.
--experimental-https-key <path>Path to a HTTPS key file.
--experimental-https-cert <path>Path to a HTTPS certificate file.
--experimental-https-ca <path>Path to a HTTPS certificate authority file.
--experimental-upload-trace <traceUrl>Reports a subset of the debugging trace to a remote HTTP URL.

next build options

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

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

OptionDescription
-h, --helpShow all available options.
[directory]A directory on which to build the application. If not provided, the current directory will be used.
-d or --debugEnables a more verbose build output. With this flag enabled additional build output like rewrites, redirects, and headers will be shown.
--profileEnables production profiling for React.
--no-lintDisables linting.
--no-manglingDisables mangling. This may affect performance and should only be used for debugging purposes.
--experimental-app-onlyBuilds only App Router routes.
--experimental-build-mode [mode]Uses an experimental build mode. (choices: "compile", "generate", default: "default")

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:

OptionDescription
-h or --helpShow all available options.
[directory]A directory on which to start the application. If no directory is provided, the current directory will be used.
-p or --port <port>Specify a port number on which to start the application. (default: 3000, env: PORT)
-H or --hostname <hostname>Specify a hostname on which to start the application (default: 0.0.0.0).
--keepAliveTimeout <keepAliveTimeout>Specify the maximum amount of milliseconds to wait before closing the inactive connections.

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:

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

OptionDescription
-h or --helpShow all available options
--verboseCollects additional information for debugging.

next lint options

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:

OptionDescription
[directory]A base directory on which to lint the application. If not provided, the current directory will be used.
-d, --dir, <dirs...>Include directory, or directories, to run ESLint.
--file, <files...>Include file, or files, to run ESLint.
--ext, [exts...]Specify JavaScript file extensions. (default: [".js", ".mjs", ".cjs", ".jsx", ".ts", ".mts", ".cts", ".tsx"])
-c, --config, <config>Uses this configuration file, overriding all other configuration options.
--resolve-plugins-relative-to, <rprt>Specify a directory where plugins should be resolved from.
--strictCreates a .eslintrc.json file using the Next.js strict configuration.
--rulesdir, <rulesdir...>Uses additional rules from this directory(s).
--fixAutomatically fix linting issues.
--fix-type <fixType>Specify the types of fixes to apply (e.g., problem, suggestion, layout).
--ignore-path <path>Specify a file to ignore.
--no-ignore <path>Disables the --ignore-path option.
--quietReports errors only.
--max-warnings [maxWarnings]Specify the number of warnings before triggering a non-zero exit code. (default: -1)
-o, --output-file, <outputFile>Specify a file to write report to.
-f, --format, <format>Uses a specific output format.
--no-inline-configPrevents comments from changing config or rules.
--report-unused-disable-directives-severity <level>Specify severity level for unused eslint-disable directives. (choices: "error", "off", "warn")
--no-cacheDisables caching.
--cache-location, <cacheLocation>Specify a location for cache.
--cache-strategy, [cacheStrategy]Specify a strategy to use for detecting changed files in the cache. (default: "metadata")
--error-on-unmatched-patternReports errors when any file patterns are unmatched.
-h, --helpDisplays this message.

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:

OptionDescription
-h, --helpShow all available options.
--enableEnables Next.js' telemetry collection.
--disableDisables Next.js' telemetry collection.

Learn more about Telemetry.

Examples

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:

Terminal
next dev -p 4000

Or using the PORT environment variable:

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

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

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

Good to know: When deploying to Vercel, HTTPS is automatically configured for your Next.js application.

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:

Terminal
next start --keepAliveTimeout 70000

Passing Node.js arguments

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

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