Skip to content

Next.js CLI

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

To get a list of the available CLI commands, run the following command inside your project directory:

Terminal
next -h

The output should look like this:

Terminal
Usage next [options] [command]
 
The Next.js CLI allows you to develop, build, start your application, and more.
 
Options:
  -v, --version                Outputs the Next.js version.
  -h, --help                   Displays this message.
 
Commands:
  build [directory] [options]  Creates an optimized production build of your application.
                               The output displays information about each route.
  dev [directory] [options]    Starts Next.js in development mode with hot-code reloading,
                               error reporting, and more.
  info [options]               Prints relevant details about the current system which can be
                               used to report Next.js bugs.
  lint [directory] [options]   Runs 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
                               is not already configured in your application.
  start [directory] [options]  Starts Next.js in production mode. The application should be
                               compiled with `next build` first.
  telemetry [options]          Allows you to enable or disable Next.js' completely
                               anonymous telemetry collection.

You can pass any node arguments to next commands:

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

Good to know: Running next without a command is the same as running next dev

Development

next dev starts the application in development mode with hot-code reloading, error reporting, and more.

To get a list of the available options with next dev, run the following command inside your project directory:

Terminal
next dev -h

The output should look like this:

Terminal
Usage: next dev [directory] [options]
 
Starts Next.js in development mode with hot-code reloading, error reporting, and more.
 
Arguments:
  [directory]                              A directory on which to build the application.
                                           If no directory is provided, the current
                                           directory will be used.
 
Options:
  --turbo                                  Starts development mode using Turbopack (beta).
  -p, --port <port>                        Specify a port number on which to start the
                                           application. (default: 3000, env: PORT)
  -H, --hostname <hostname>                Specify a hostname on which to start the
                                           application (default: 0.0.0.0).
  --experimental-https                     Starts 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. Includes sensitive data.
  -h, --help                               Displays this message.

The application will start at http://localhost:3000 by default. The default port can be changed with -p, 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.
  • Next.js will automatically retry with another port until a port is available if a port is not specified with the CLI option --port or the PORT environment variable.

You can also set the hostname to be different from the default of 0.0.0.0, this can be useful for making the application available for other devices on the network. The default hostname can be changed with -H, like so:

Terminal
next dev -H 192.168.1.2

Turbopack

Turbopack (beta), our new bundler, which is being tested and stabilized in Next.js, helps speed up local iterations while working on your application.

To use Turbopack in development mode, add the --turbo option:

Terminal
next dev --turbo

HTTPS for Local Development

For certain use cases like webhooks or authentication, it may be required to use HTTPS to have a secure environment on localhost. Next.js can generate a self-signed certificate with next dev as follows:

Terminal
next dev --experimental-https

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. When deploying to Vercel, HTTPS is automatically configured for your Next.js application.

Build

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

Terminal
Route (app)                               Size     First Load JS
 /                                     5.3 kB         89.5 kB
 /_not-found                           885 B          85.1 kB
 /about                                137 B          84.4 kB
+ First Load JS shared by all             84.2 kB
chunks/184-d3bb186aac44da98.js        28.9 kB
chunks/30b509c0-f3503c24f98f3936.js   53.4 kB
other shared chunks (total)
 
 
○  (Static)  prerendered as static content
  • Size: The number of assets downloaded when navigating to the page client-side. The size for each route only includes its dependencies.
  • First Load JS: The number 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.

To get a list of the available options with next build, run the following command inside your project directory:

Terminal
next build -h

The output should look like this:

Terminal
Usage: next build [directory] [options]
 
Creates an optimized production build of your application. The output displays information
about each route.
 
Arguments:
  [directory]                       A directory on which to build the application. If no
                                    provided, the current directory will be
                                    used.
 
Options:
  -d, --debug                       Enables a more verbose build output.
  --profile                         Enables production profiling for React.
  --no-lint                         Disables linting.
  --no-mangling                     Disables mangling.
  --experimental-app-only           Builds only App Router routes.
  --experimental-build-mode [mode]  Uses an experimental build mode. (choices: "compile"
                                    "generate", default: "default")
  -h, --help                        Displays this message.

Profiling

You can enable production profiling for React with the --profile flag in next build.

Terminal
next build --profile

After that, you can use the profiler in the same way as you would in development.

Debug

You can enable more verbose build output with the --debug flag in next build.

Terminal
next build --debug

With this flag enabled additional build output like rewrites, redirects, and headers will be shown.

Linting

You can disable linting for builds like so:

Terminal
next build --no-lint

Mangling

You can disable mangling for builds like so:

Terminal
next build --no-mangling

Good to know: This may affect performance and should only be used for debugging purposes.

Production

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

To get a list of the available options with next start, run the follow command inside your project directory:

Terminal
next start -h

The output should look like this:

Terminal
Usage: next start [directory] [options]
 
Starts Next.js in production mode. The application should be compiled with `next build`
first.
 
Arguments:
  [directory]                           A directory on which to start the application.
                                        If not directory is provided, the current
                                        directory will be used.
 
Options:
  -p, --port <port>                     Specify a port number on which to start the
                                        application. (default: 3000, env: PORT)
  -H, --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.
  -h, --help                            Displays this message.

The application will start at http://localhost:3000 by default. The default port can be changed with -p, like so:

Terminal
next start -p 4000

Or using the PORT environment variable:

Terminal
PORT=4000 next start

Good to know:

  • PORT cannot be set in .env as booting up the HTTP server happens before any other code is initialized.
  • next start cannot be used with output: 'standalone' or output: 'export'.

Keep Alive Timeout

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

Info

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

To get a list of the available options with next info, run the following command inside your project directory:

Terminal
next info -h

The output should look like this:

Terminal
Usage: next info [options]
 
Prints relevant details about the current system which can be used to report Next.js bugs.
 
Options:
  --verbose   Collections additional information for debugging.
  -h, --help  Displays this message.

Running next info will give you information like this example:

Terminal
 
Operating System:
  Platform: linux
  Arch: x64
  Version: #22-Ubuntu SMP Fri Nov 5 13:21:36 UTC 2021
  Available memory (MB): 31795
  Available CPU cores: 16
Binaries:
  Node: 16.13.0
  npm: 8.1.0
  Yarn: 1.22.17
  pnpm: 6.24.2
Relevant Packages:
  next: 14.1.1-canary.61 // Latest available version is detected (14.1.1-canary.61).
  react: 18.2.0
  react-dom: 18.2.0
Next.js Config:
  output: N/A
 

This information should then be pasted into GitHub Issues.

You can also run next info --verbose which will print additional information about the system and the installation of packages related to next.

Lint

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.

To get a list of the available options with next lint, run the following command inside your project directory:

Terminal
next lint -h

The output should look like this:

Terminal
Usage: next lint [directory] [options]
 
Runs 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
is not already configured in your application.
 
Arguments:
  [directory]                            A base directory on which to lint the application.
                                         If no directory is provided, the current
                                         directory will be used.
 
Options:
  -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", ".ts
x"])
  -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.
  --strict                               Creates a `.eslintrc.json` file using the Next.js
                                         strict configuration.
  --rulesdir, <rulesdir...>              Uses additional rules from this directory(s).
  --fix                                  Automatically 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.
  --quiet                                Reports 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 specifc output format.
  --no-inline-config                     Prevents comments from changing config or rules.
  --report-unused-disable-directives     Adds reprted errors for unused eslint-disable
                                         directives.
  --no-cache                             Disables 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-pattern           Reports errors when any file patterns are
                                         unmatched.
  -h, --help                             Displays this message.

If you have other directories that you would like to lint, you can specfy them using the --dir flag:

Terminal
next lint --dir utils

For more information on the other options, check out our ESLint configuration documentation.

Telemetry

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

To get a list of the available options with next telemetry, run the following command in your project directory:

Terminal
next telemetry -h

The output should look like this:

Terminal
Usage: next telemetry [options]
 
Allows you to enable or disable Next.js' completely anonymous telemetry collection.
 
Options:
  --enable    Eanbles Next.js' telemetry collection.
  --disable   Disables Next.js' telemetry collection.
  -h, --help  Displays this message.
 
Learn more: https://nextjs.org/telemetry

Learn more about Telemetry.