| --- | |
| 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. | | |