File size: 25,426 Bytes
b91e262 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 | ---
title: next CLI
description: Learn how to run and build your application with the Next.js CLI.
---
{/* 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 develop, build, start your application, and more.
Basic usage:
```bash filename="Terminal"
npx next [command] [options]
```
## Reference
The following options are available:
| Options | Description |
| ------------------- | ---------------------------------- |
| `-h` or `--help` | Shows all available options |
| `-v` or `--version` | Outputs the Next.js version number |
### Commands
The following commands are available:
| Command | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| [`dev`](#next-dev-options) | Starts Next.js in development mode with Hot Module Reloading, error reporting, and more. |
| [`build`](#next-build-options) | Creates an optimized production build of your application. Displaying information about each route. |
| [`start`](#next-start-options) | Starts Next.js in production mode. The application should be compiled with `next build` first. |
| [`info`](#next-info-options) | Prints relevant details about the current system which can be used to report Next.js bugs. |
| [`telemetry`](#next-telemetry-options) | Allows you to enable or disable Next.js' completely anonymous telemetry collection. |
| [`typegen`](#next-typegen-options) | Generates TypeScript definitions for routes, pages, layouts, and route handlers without running a full build. |
| [`upgrade`](#next-upgrade-options) | Upgrades your Next.js application to the latest version. |
| [`experimental-analyze`](#next-experimental-analyze-options) | Analyzes bundle output using Turbopack. Does not produce build artifacts. |
> **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`:
| Option | Description |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h, --help` | Show all available options. |
| `[directory]` | A directory in which to build the application. If not provided, current directory is used. |
| `--turbopack` | Force enable [Turbopack](/docs/app/api-reference/turbopack) (enabled by default). Also available as `--turbo`. |
| `--webpack` | Use Webpack instead of the default [Turbopack](/docs/app/api-reference/turbopack) bundler for development. |
| `-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. Useful for making the application available for other devices on the network. 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. |
| `--experimental-cpu-prof` | Enables CPU profiling using V8's inspector. Profiles are saved to `.next/cpu-profiles/` on exit. |
### `next build` options
`next build` creates an optimized production build of your application. The output displays information about each route. For example:
```bash filename="Terminal"
Route (app)
┌ ○ /_not-found
└ ƒ /products/[id]
○ (Static) prerendered as static content
ƒ (Dynamic) server-rendered on demand
```
The following options are available for the `next build` command:
| Option | Description |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h, --help` | Show all available options. |
| `[directory]` | A directory on which to build the application. If not provided, the current directory will be used. |
| `--turbopack` | Force enable [Turbopack](/docs/app/api-reference/turbopack) (enabled by default). Also available as `--turbo`. |
| `--webpack` | Build using Webpack. |
| `-d` or `--debug` | Enables a more verbose build output. With this flag enabled additional build output like rewrites, redirects, and headers will be shown. |
| |
| `--profile` | Enables production [profiling for React](https://react.dev/reference/react/Profiler). |
| `--no-lint` | Disables linting. _Note: linting will be removed from `next build` in Next 16. If you're using Next 15.5+ with a linter other than `eslint`, linting during build will not occur._ |
| `--no-mangling` | Disables [mangling](https://en.wikipedia.org/wiki/Name_mangling). This may affect performance and should only be used for debugging purposes. |
| `--experimental-app-only` | Builds only App Router routes. |
| `--experimental-build-mode [mode]` | Uses an experimental build mode. (choices: "compile", "generate", default: "default") |
| `--debug-prerender` | Debug prerender errors in development. |
| `--debug-build-paths=<patterns>` | Build only specific routes for debugging. |
| `--experimental-cpu-prof` | Enables CPU profiling using V8's inspector. Profiles are saved to `.next/cpu-profiles/` on exit. |
### `next start` options
`next start` starts the application in production mode. The application should be compiled with [`next build`](#next-build-options) first.
The following options are available for the `next start` command:
| Option | Description |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `-h` or `--help` | Show 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. |
| `--experimental-cpu-prof` | Enables CPU profiling using V8's inspector. Profiles are saved to `.next/cpu-profiles/` on exit. |
### `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](https://github.com/vercel/next.js/issues). 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:
```bash filename="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:
| Option | Description |
| ---------------- | ---------------------------------------------- |
| `-h` or `--help` | Show all available options |
| `--verbose` | Collects additional information for debugging. |
### `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:
| Option | Description |
| ------------ | --------------------------------------- |
| `-h, --help` | Show all available options. |
| `--enable` | Enables Next.js' telemetry collection. |
| `--disable` | Disables Next.js' telemetry collection. |
Learn more about [Telemetry](/telemetry).
### `next typegen` options
`next typegen` generates TypeScript definitions for your application's routes without performing a full build. This is useful for IDE autocomplete and CI type-checking of route usage.
Previously, route types were only generated during `next dev` or `next build`, which meant running `tsc --noEmit` directly wouldn't validate your route types. Now you can generate types independently and validate them externally:
```bash filename="Terminal"
# Generate route types first, then validate with TypeScript
next typegen && tsc --noEmit
# Or in CI workflows for type checking without building
next typegen && npm run type-check
```
The following options are available for the `next typegen` command:
| Option | Description |
| ------------- | -------------------------------------------------------------------------------------------- |
| `-h, --help` | Show all available options. |
| `[directory]` | A directory on which to generate types. If not provided, the current directory will be used. |
Output files are written to `<distDir>/types` (typically: `.next/dev/types` or `.next/types`, see [`isolatedDevBuild`](/docs/app/api-reference/config/next-config-js/isolatedDevBuild)):
```bash filename="Terminal"
next typegen
# or for a specific app
next typegen ./apps/web
```
Additionally, `next typegen` generates a `next-env.d.ts` file. We recommend adding `next-env.d.ts` to your `.gitignore` file.
The `next-env.d.ts` file is included into your `tsconfig.json` file, to make Next.js types available to your project.
To ensure `next-env.d.ts` is present before type-checking run `next typegen`. The commands `next dev` and `next build` also generate the `next-env.d.ts` file, but it is often undesirable to run these just to type-check, for example in CI/CD environments.
> **Good to know**: `next typegen` loads your Next.js config (`next.config.js`, `next.config.mjs`, or `next.config.ts`) using the production build phase. Ensure any required environment variables and dependencies are available so the config can load correctly.
### `next upgrade` options
`next upgrade` upgrades your Next.js application to the latest version.
The following options are available for the `next upgrade` command:
| Option | Description |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h, --help` | Show all available options. |
| `[directory]` | A directory with the Next.js application to upgrade. If not provided, the current directory will be used. |
| `--revision <revision>` | Specify a Next.js version or tag to upgrade to (e.g., `latest`, `canary`, `15.0.0`). Defaults to the release channel you have currently installed. |
| `--verbose` | Show verbose output during the upgrade process. |
### `next experimental-analyze` options
`next experimental-analyze` analyzes your application's bundle output using [Turbopack](/docs/app/api-reference/turbopack). This command helps you understand the size and composition of your bundles, including JavaScript, CSS, and other assets. This command doesn't produce an application build.
```bash filename="Terminal"
npx next experimental-analyze
```
By default, the command starts a local server after analysis completes, allowing you to explore your bundle composition in the browser. The analyzer lets you:
- Filter bundles by route and switch between client and server views
- View the full import chain showing why a module is included
- Trace imports across server-to-client component boundaries and dynamic imports
See [Package Bundling](/docs/app/guides/package-bundling#optimizing-large-bundles) for optimization strategies.
To write the analysis output to disk without starting the server, use the `--output` flag. The output is written to `.next/diagnostics/analyze` and contains static files that can be copied elsewhere or shared with others:
```bash filename="Terminal"
# Write output to .next/diagnostics/analyze
npx next experimental-analyze --output
# Copy the output for comparison with a future analysis
cp -r .next/diagnostics/analyze ./analyze-before-refactor
```
The following options are available for the `next experimental-analyze` command:
| Option | Description |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `-h, --help` | Show all available options. |
| `[directory]` | A directory on which to analyze the application. If not provided, the current directory will be used. |
| `--no-mangling` | Disables [mangling](https://en.wikipedia.org/wiki/Name_mangling). This may affect performance and should only be used for debugging purposes. |
| `--profile` | Enables production [profiling for React](https://react.dev/reference/react/Profiler). This may affect performance. |
| `-o, --output` | Write analysis files to disk without starting the server. Output is written to `.next/diagnostics/analyze`. |
| `--port <port>` | Specify a port number to serve the analyzer on. (default: 4000, env: PORT) |
## Examples
### Debugging prerender errors
If you encounter prerendering errors during `next build`, you can pass the `--debug-prerender` flag to get more detailed output:
```bash filename="Terminal"
next build --debug-prerender
```
This enables several experimental options to make debugging easier:
- Disables server code minification:
- `experimental.serverMinification = false`
- `experimental.turbopackMinify = false`
- Generates source maps for server bundles:
- `experimental.serverSourceMaps = true`
- Enables source map consumption in child processes used for prerendering:
- `enablePrerenderSourceMaps = true`
- Continues building even after the first prerender error, so you can see all issues at once:
- `experimental.prerenderEarlyExit = false`
This helps surface more readable stack traces and code frames in the build output.
> **Warning**: `--debug-prerender` is for debugging in development only. Do not deploy builds generated with `--debug-prerender` to production, as it may impact performance.
### Building specific routes
You can build only specific routes in the App and Pages Routers using the `--debug-build-paths` option. This is useful for faster debugging when working with large applications. The `--debug-build-paths` option accepts comma-separated file paths and supports glob patterns:
```bash filename="Terminal"
# Build a specific route
next build --debug-build-paths="app/page.tsx"
# Build more than one route
next build --debug-build-paths="app/page.tsx,pages/index.tsx"
# Use glob patterns
next build --debug-build-paths="app/**/page.tsx"
next build --debug-build-paths="pages/*.tsx"
```
### 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:
```bash filename="Terminal"
next dev -p 4000
```
Or using the `PORT` environment variable:
```bash filename="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](https://developer.mozilla.org/en-US/docs/Glossary/HTTPS) to have a secure environment on `localhost`. Next.js can generate a self-signed certificate with `next dev` using the `--experimental-https` flag:
```bash filename="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.
```bash filename="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`](https://github.com/FiloSottile/mkcert). In production, use properly issued certificates from trusted authorities.
### 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](https://nodejs.org/api/http.html#http_server_keepalivetimeout) 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:
```bash filename="Terminal"
next start --keepAliveTimeout 70000
```
### Passing Node.js arguments
You can pass any [node arguments](https://nodejs.org/api/cli.html#cli_node_options_options) to `next` commands. For example:
```bash filename="Terminal"
NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm' next
NODE_OPTIONS='--inspect' next
```
### CPU profiling
You can capture CPU profiles to analyze performance bottlenecks in your Next.js application. The `--experimental-cpu-prof` flag enables V8's built-in CPU profiler and saves profiles to `.next/cpu-profiles/` when the process exits:
```bash filename="Terminal"
# Profile the build process
next build --experimental-cpu-prof
# Profile the dev server (profile saved on Ctrl+C or SIGTERM)
next dev --experimental-cpu-prof
# Profile the production server
next start --experimental-cpu-prof
```
The generated `.cpuprofile` files can be opened in Chrome DevTools (Performance tab → Load profile) or other V8-compatible profiling tools.
> **Good to know**: Profile files are named with a descriptive prefix and timestamp. The profiles generated depend on the command:
>
> **`next dev`:**
>
> - `dev-main-*` - Parent process (dev server orchestration)
> - `dev-server-*` - Child server process (request handling and rendering) - this is typically what you want to analyze
>
> **`next build` (Turbopack):**
>
> - `build-main-*` - Main build orchestration process
> - `build-turbopack-*` - Turbopack compilation worker
>
> **`next build` (Webpack):**
>
> - `build-main-*` - Main build orchestration process
> - `build-webpack-client-*` - Client bundle compilation worker
> - `build-webpack-server-*` - Server bundle compilation worker
> - `build-webpack-edge-server-*` - Edge runtime compilation worker
>
> **`next start`:**
>
> - `start-main-*` - Production server process
| Version | Changes |
| --------- | ------------------------------------------------------------------------------- |
| `v16.1.0` | Add the `next experimental-analyze` command |
| `v16.0.0` | The JS bundle size metrics have been removed from `next build` |
| `v15.5.0` | Add the `next typegen` command |
| `v15.4.0` | Add `--debug-prerender` option for `next build` to help debug prerender errors. |
|