Unverified Commit ccbd69ff authored by Sam Ko's avatar Sam Ko Committed by GitHub

docs: update Next.js CLI docs (#62304)

## Description

It made sense to improve our <picture data-single-emoji=":nextjs:"
title=":nextjs:"><img class="emoji" width="20" height="auto"
src="https://emoji.slack-edge.com/T0CAQ00TU/nextjs/2a85d633ae594556.png"
alt=":nextjs:" align="absmiddle"></picture> CLI docs after refactoring
the CLI!

## Important Changes
- Removes mention of `next export`, which was moved to `next.config.js`
- Adds mention of `--turbo`
- Adds all the expected help outputs

## Related
- https://github.com/vercel/next.js/pull/61877
- Fixes https://github.com/vercel/next.js/issues/59226

Closes NEXT-2545

---------
Co-authored-by: 's avatarDelba de Oliveira <32464864+delbaoliveira@users.noreply.github.com>
Co-authored-by: 's avatarMichael Novotny <manovotny@gmail.com>
Co-authored-by: 's avatarLee Robinson <me@leerob.io>
Co-authored-by: 's avatarJJ Kasper <jj@jjsweb.site>
parent 47f73cd8
--- ---
title: Next.js CLI title: Next.js CLI
description: The Next.js CLI allows you to start, build, and export your application. Learn more about it here. description: Learn how the Next.js CLI allows you to develop, build, and start your application, and more.
--- ---
{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */} {/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
The Next.js CLI allows you to start, build, and export your application. 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: To get a list of the available CLI commands, run the following command inside your project directory:
```bash filename="Terminal" ```bash filename="Terminal"
npx next -h next -h
``` ```
_([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) comes with npm 5.2+ and higher)_
The output should look like this: The output should look like this:
```bash filename="Terminal" ```bash filename="Terminal"
Usage Usage next [options] [command]
$ next <command>
The Next.js CLI allows you to develop, build, start your application, and more.
Available commands
build, start, export, dev, lint, telemetry, info Options:
-v, --version Outputs the Next.js version.
Options -h, --help Displays this message.
--version, -v Version number
--help, -h Displays this message Commands:
build [directory] [options] Creates an optimized production build of your application.
For more information run a command with the --help flag The output displays information about each route.
$ next build --help 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](https://nodejs.org/api/cli.html#cli_node_options_options) to `next` commands: You can pass any [node arguments](https://nodejs.org/api/cli.html#cli_node_options_options) to `next` commands:
...@@ -42,45 +51,54 @@ NODE_OPTIONS='--inspect' next ...@@ -42,45 +51,54 @@ NODE_OPTIONS='--inspect' next
> **Good to know**: Running `next` without a command is the same as running `next dev` > **Good to know**: Running `next` without a command is the same as running `next dev`
## Build ## Development
`next build` creates an optimized production build of your application. The output displays information about each route.
- **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. `next dev` starts the application in development mode with hot-code reloading, error reporting, and more.
You can enable production profiling for React with the `--profile` flag in `next build`. This requires [Next.js 9.5](https://nextjs.org/blog/next-9-5): To get a list of the available options with `next dev`, run the following command inside your project directory:
```bash filename="Terminal" ```bash filename="Terminal"
next build --profile next dev -h
``` ```
After that, you can use the profiler in the same way as you would in development. The output should look like this:
You can enable more verbose build output with the `--debug` flag in `next build`. This requires Next.js 9.5.3:
```bash filename="Terminal" ```bash filename="Terminal"
next build --debug 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.
``` ```
With this flag enabled additional build output like rewrites, redirects, and headers will be shown.
## Development
`next dev` starts the application in development mode with hot-code reloading, error reporting, and more:
The application will start at `http://localhost:3000` by default. The default port can be changed with `-p`, like so: The application will start at `http://localhost:3000` by default. The default port can be changed with `-p`, like so:
```bash filename="Terminal" ```bash filename="Terminal"
npx next dev -p 4000 next dev -p 4000
``` ```
Or using the `PORT` environment variable: Or using the `PORT` environment variable:
```bash filename="Terminal" ```bash filename="Terminal"
PORT=4000 npx next dev 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. > **Good to know**: `PORT` cannot be set in `.env` as booting up the HTTP server happens before any other code is initialized.
...@@ -88,7 +106,17 @@ PORT=4000 npx next dev ...@@ -88,7 +106,17 @@ PORT=4000 npx next dev
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: 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:
```bash filename="Terminal" ```bash filename="Terminal"
npx next dev -H 192.168.1.2 next dev -H 192.168.1.2
```
### Turbopack
[Turbopack](https://turbo.build/pack) (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:
```bash filename="Terminal"
next dev --turbo
``` ```
### HTTPS for Local Development ### HTTPS for Local Development
...@@ -107,20 +135,140 @@ next dev --experimental-https --experimental-https-key ./certificates/localhost- ...@@ -107,20 +135,140 @@ next dev --experimental-https --experimental-https-key ./certificates/localhost-
`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](https://vercel.com/docs/security/encryption) for your Next.js application. `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](https://vercel.com/docs/security/encryption) for your Next.js application.
## Build
`next build` creates an optimized production build of your application. The output displays information about each route:
```bash filename="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**](/docs/app/api-reference/next-config-js/compress). 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:
```bash filename="Terminal"
next build -h
```
The output should look like this:
```bash filename="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`.
```bash filename="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`.
```bash filename="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:
```bash filename="Terminal"
next build --no-lint
```
### Mangling
You can disable [mangling](https://en.wikipedia.org/wiki/Name_mangling) for builds like so:
```bash filename="Terminal"
next build --no-mangling
```
> **Good to know**: This may affect performance and should only be used for debugging purposes.
## Production ## Production
`next start` starts the application in production mode. The application should be compiled with [`next build`](#build) first. `next start` starts the application in production mode. The application should be compiled with [`next build`](#build) first.
To get a list of the available options with `next start`, run the follow command inside your project directory:
```bash filename="Terminal"
next start -h
```
The output should look like this:
```bash filename="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: The application will start at `http://localhost:3000` by default. The default port can be changed with `-p`, like so:
```bash filename="Terminal" ```bash filename="Terminal"
npx next start -p 4000 next start -p 4000
``` ```
Or using the `PORT` environment variable: Or using the `PORT` environment variable:
```bash filename="Terminal" ```bash filename="Terminal"
PORT=4000 npx next start PORT=4000 next start
``` ```
> **Good to know**: > **Good to know**:
...@@ -136,7 +284,7 @@ When deploying Next.js behind a downstream proxy (e.g. a load-balancer like AWS ...@@ -136,7 +284,7 @@ When deploying Next.js behind a downstream proxy (e.g. a load-balancer like AWS
To configure the timeout values for the production Next.js server, pass `--keepAliveTimeout` (in milliseconds) to `next start`, like so: To configure the timeout values for the production Next.js server, pass `--keepAliveTimeout` (in milliseconds) to `next start`, like so:
```bash filename="Terminal" ```bash filename="Terminal"
npx next start --keepAliveTimeout 70000 next start --keepAliveTimeout 70000
``` ```
## Info ## Info
...@@ -144,13 +292,25 @@ npx next start --keepAliveTimeout 70000 ...@@ -144,13 +292,25 @@ npx next start --keepAliveTimeout 70000
`next info` prints relevant details about the current system which can be used to report Next.js bugs. `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`). This information includes Operating System platform/arch/version, Binaries (Node.js, npm, Yarn, pnpm) and npm package versions (`next`, `react`, `react-dom`).
Running the following in your project's root directory: To get a list of the available options with `next info`, run the following command inside your project directory:
```bash filename="Terminal"
next info -h
```
The output should look like this:
```bash filename="Terminal" ```bash filename="Terminal"
next info 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.
``` ```
will give you information like this example: Running `next info` will give you information like this example:
```bash filename="Terminal" ```bash filename="Terminal"
...@@ -184,16 +344,93 @@ You can also run `next info --verbose` which will print additional information a ...@@ -184,16 +344,93 @@ You can also run `next info --verbose` which will print additional information a
provides a guided setup to install any required dependencies if ESLint is not already configured in provides a guided setup to install any required dependencies if ESLint is not already configured in
your application. your application.
If you have other directories that you would like to lint, you can specify them using the `--dir` To get a list of the available options with `next lint`, run the following command inside your project directory:
flag:
```bash filename="Terminal"
next lint -h
```
The output should look like this:
```bash filename="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:
```bash filename="Terminal" ```bash filename="Terminal"
next lint --dir utils next lint --dir utils
``` ```
For more information on the other options, check out our [ESLint](/docs/app/building-your-application/configuring/eslint) configuration documentation.
## Telemetry ## Telemetry
Next.js collects **completely anonymous** telemetry data about general usage. 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. Participation in this anonymous program is optional, and you may opt-out if you'd not like to share any information.
To learn more about Telemetry, [please read this document](https://nextjs.org/telemetry/). To get a list of the available options with `next telemetry`, run the following command in your project directory:
```bash filename="Terminal"
next telemetry -h
```
The output should look like this:
```bash filename="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](/telemetry/).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment