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:
next -h
The output should look like this:
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:
NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next
Good to know: Running
nextwithout a command is the same as runningnext 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:
next dev -h
The output should look like this:
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:
next dev -p 4000
Or using the PORT environment variable:
PORT=4000 next dev
Good to know:
PORTcannot be set in.envas 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
--portor thePORTenvironment 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:
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:
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:
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.
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:
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:
next build -h
The output should look like this:
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.
Debug
You can enable more verbose build output with the --debug flag in next build.
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:
next build --no-lint
Mangling
You can disable mangling for builds like so:
next build --no-mangling
Good to know: This may affect performance and should only be used for debugging purposes.
Profiling
You can enable production profiling for React with the --profile flag in next build.
next build --profile
After that, you can use the profiler in the same way as you would in development.
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:
next start -h
The output should look like this:
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:
next start -p 4000
Or using the PORT environment variable:
PORT=4000 next start
Good to know:
PORTcannot be set in.envas booting up the HTTP server happens before any other code is initialized.next startcannot be used withoutput: 'standalone'oroutput: '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:
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:
next info -h
The output should look like this:
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:
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:
next lint -h
The output should look like this:
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", ".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.
--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-severity <level> Specify severity level for unused eslint-disable
directives. (choices: "error", "off", "warn")
--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 specify them using the --dir flag:
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:
next telemetry -h
The output should look like this:
Usage: next telemetry [options]
Allows you to enable or disable Next.js' completely anonymous telemetry collection.
Options:
--enable Enables 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.