functions

556 notes in this subject, read out of this brain and free to use. This is page 10 of 10.

next typegen command purpose

The `next typegen` command generates TypeScript definitions for application routes without performing a full build. This enables IDE autocomplete and CI type-checking of route usage. Route types were previously only generated during `next dev` or `next build`, so `tsc --noEmit` directly wouldn't validate route types. Now types can be generated independently with `next typegen && tsc --noEmit` or in CI workflows with `next typegen && npm run type-check`.

next typegen options

Options for `next typegen`: `-h, --help` (show options), `[directory]` (directory to generate types for, default: current). Output files are written to `<distDir>/types` (typically `.next/dev/types` in development or `.next/types` in production). The command generates a `next-env.d.ts` file which should be added to `.gitignore`. This file is included in `tsconfig.json` to make Next.js types available to the project.

next typegen configuration loading

The `next typegen` command loads the 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

Options for `next upgrade`: `-h, --help` (show options), `[directory]` (directory with Next.js app to upgrade, default: current), `--revision <revision>` (Next.js version or tag to upgrade to, e.g., `latest`, `canary`, `15.0.0`, defaults to current release channel), `--verbose` (show verbose output during upgrade).

Debugging prerender errors with --debug-prerender

When encountering prerendering errors during `next build`, the `--debug-prerender` flag provides detailed output by disabling server code minification (`experimental.serverMinification = false`, `experimental.turbopackMinify = false`), generating source maps for server bundles (`experimental.serverSourceMaps = true`), and continuing building after the first error so all issues are visible at once (`experimental.prerenderEarlyExit = false`). This surfaces more readable stack traces and code frames. Warning: `--debug-prerender` is for development debugging only and should not be deployed to production as it impacts performance.

CPU profile file naming conventions

CPU profile files are named with descriptive prefixes and timestamps. For `next dev`: `dev-main-*` (parent process for dev server orchestration), `dev-server-*` (child server process for request handling and rendering, typically what to analyze). For `next build` with Turbopack: `build-main-*` (main build orchestration), `build-turbopack-*` (Turbopack compilation worker). For `next build` with Webpack: `build-main-*` (main orchestration), `build-webpack-client-*` (client bundle worker), `build-webpack-server-*` (server bundle worker), `build-webpack-edge-server-*` (edge runtime worker). For `next start`: `start-main-*` (production server process).

CPU profiling with Next.js CLI

CPU profiles can be captured with the `--experimental-cpu-prof` flag to analyze performance bottlenecks. The flag enables V8's CPU profiler and saves profiles to `.next-profiles/` when the process exits. Usage: `next build --experimental-cpu-prof` (profile build), `next dev --experimental-cpu-prof` (profile dev server, saved on Ctrl+C or SIGTERM), `next start --experimental-cpu-prof` (profile production server). Generated `.cpuprofile` files can be opened in Chrome DevTools (Performance tab → Load profile) or V8-compatible tools.

Passing Node.js arguments to next commands

Node.js arguments can be passed to `next` commands using the `NODE_OPTIONS` environment variable. Examples: `NODE_OPTIONS='--throw-deprecation' next`, `NODE_OPTIONS='-r esm' next`, `NODE_OPTIONS='--inspect' next`.

Configuring keep-alive timeout for downstream proxies

When deploying Next.js behind a downstream proxy like AWS ELB/ALB, configure the HTTP server with keep-alive timeouts larger than the proxy's timeouts using `--keepAliveTimeout` (in milliseconds) with `next start`. For example: `next start --keepAliveTimeout 70000`. Without this, Node.js terminates connections without notifying the proxy, causing proxy errors when reusing terminated connections.

Using HTTPS during development

For use cases like webhooks or authentication, HTTPS can be used on localhost with `next dev --experimental-https`, which generates a self-signed certificate. The server will exist at `https://localhost:3000` with default port 3000 unless overridden with `-p`, `--port`, or `PORT`. Custom certificate and key can be provided with `--experimental-https-key` and `--experimental-https-cert`, and optionally a CA certificate with `--experimental-https-ca`. This is only for development and uses `mkcert` to create a locally trusted certificate; production requires properly issued certificates from trusted authorities.

Changing default port for Next.js

The default port for Next.js development and `next start` is `http://localhost:3000`. It can be changed with the `-p` option (e.g., `next dev -p 4000`) or the `PORT` environment variable (e.g., `PORT=4000 next dev`). Note that `PORT` cannot be set in `.env` as the HTTP server boots before other code is initialized.

next experimental-analyze options

Options for `next experimental-analyze`: `-h, --help` (show options), `[directory]` (directory to analyze, default: current), `--no-mangling` (disable name mangling for debugging), `--profile` (enable production React profiling), `-o, --output` (write analysis to disk without starting server; output written to `.next/diagnostics/analyze`), `--port <port>` (port to serve analyzer on, default: 4000, env: PORT).

Building specific routes with --debug-build-paths

The `--debug-build-paths` option for `next build` allows building only specific routes for faster debugging in large applications. It accepts comma-separated file paths, supports glob patterns, and excludes paths prefixed with `!`. Examples: `next build --debug-build-paths="app/page.tsx"` (single route), `next build --debug-build-paths="app/page.tsx,pages/index.tsx"` (multiple routes), `next build --debug-build-paths="app/(marketing)/about/page.tsx"` (route groups), `next build --debug-build-paths="app/**/page.tsx"` (glob patterns), `next build --debug-build-paths="app/**/page.tsx,!app/admin/**"` (exclude with !). In projects with routes under `src/`, paths resolve with or without `src/` prefix, so both `app/page.tsx` and `src/app/page.tsx` match the same route.

next build output format for routes

The `next build` command displays route information with symbols: `○` (Static) indicates prerendered as static content, `ƒ` (Dynamic) indicates server-rendered on demand. Example output shows Route (app), `/_not-found` as static, and `/products/[id]` as dynamic.

next experimental-analyze output to disk

The `next experimental-analyze --output` flag writes analysis output to disk without starting the server. Output is written to `.next/diagnostics/analyze` and contains static files that can be copied or shared. Example: `npx next experimental-analyze --output` writes to `.next/diagnostics/analyze`, and `cp -r .next/diagnostics/analyze ./analyze-before-refactor` copies for comparison with future analysis.

next experimental-analyze command

The `next experimental-analyze` command analyzes application bundle output using Turbopack to understand bundle size and composition including JavaScript, CSS, and other assets. It does not produce an application build. By default, it starts a local server to explore bundle composition in the browser, with filtering by route, client/server view switching, and full import chain visualization.

Give your agent this brain