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: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com> Co-authored-by: Michael Novotny <manovotny@gmail.com> Co-authored-by: Lee Robinson <me@leerob.io> Co-authored-by: JJ Kasper <jj@jjsweb.site>
This commit is contained in:
parent
47f73cd8ec
commit
ccbd69ff9a
1 changed files with 289 additions and 52 deletions
|
@ -1,35 +1,44 @@
|
|||
---
|
||||
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 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:
|
||||
|
||||
```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:
|
||||
|
||||
```bash filename="Terminal"
|
||||
Usage
|
||||
$ next <command>
|
||||
Usage next [options] [command]
|
||||
|
||||
Available commands
|
||||
build, start, export, dev, lint, telemetry, info
|
||||
The Next.js CLI allows you to develop, build, start your application, and more.
|
||||
|
||||
Options
|
||||
--version, -v Version number
|
||||
--help, -h Displays this message
|
||||
Options:
|
||||
-v, --version Outputs the Next.js version.
|
||||
-h, --help Displays this message.
|
||||
|
||||
For more information run a command with the --help flag
|
||||
$ next build --help
|
||||
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](https://nodejs.org/api/cli.html#cli_node_options_options) to `next` commands:
|
||||
|
@ -42,45 +51,54 @@ NODE_OPTIONS='--inspect' next
|
|||
|
||||
> **Good to know**: Running `next` without a command is the same as running `next dev`
|
||||
|
||||
## Build
|
||||
|
||||
`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.
|
||||
|
||||
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):
|
||||
|
||||
```bash filename="Terminal"
|
||||
next build --profile
|
||||
```
|
||||
|
||||
After that, you can use the profiler in the same way as you would in development.
|
||||
|
||||
You can enable more verbose build output with the `--debug` flag in `next build`. This requires Next.js 9.5.3:
|
||||
|
||||
```bash filename="Terminal"
|
||||
next build --debug
|
||||
```
|
||||
|
||||
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:
|
||||
`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:
|
||||
|
||||
```bash filename="Terminal"
|
||||
next dev -h
|
||||
```
|
||||
|
||||
The output should look like this:
|
||||
|
||||
```bash filename="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:
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx next dev -p 4000
|
||||
next dev -p 4000
|
||||
```
|
||||
|
||||
Or using the `PORT` environment variable:
|
||||
|
||||
```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.
|
||||
|
@ -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:
|
||||
|
||||
```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
|
||||
|
@ -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.
|
||||
|
||||
## 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
|
||||
|
||||
`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:
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx next start -p 4000
|
||||
next start -p 4000
|
||||
```
|
||||
|
||||
Or using the `PORT` environment variable:
|
||||
|
||||
```bash filename="Terminal"
|
||||
PORT=4000 npx next start
|
||||
PORT=4000 next start
|
||||
```
|
||||
|
||||
> **Good to know**:
|
||||
|
@ -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:
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx next start --keepAliveTimeout 70000
|
||||
next start --keepAliveTimeout 70000
|
||||
```
|
||||
|
||||
## Info
|
||||
|
@ -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.
|
||||
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
|
||||
next info -h
|
||||
```
|
||||
|
||||
will give you information like this example:
|
||||
The output should look like this:
|
||||
|
||||
```bash filename="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:
|
||||
|
||||
```bash filename="Terminal"
|
||||
|
||||
|
@ -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
|
||||
your application.
|
||||
|
||||
If you have other directories that you would like to lint, you can specify them using the `--dir`
|
||||
flag:
|
||||
To get a list of the available options with `next lint`, run the following command inside your project directory:
|
||||
|
||||
```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"
|
||||
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
|
||||
|
||||
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 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/).
|
||||
|
|
Loading…
Reference in a new issue