Next.js Docs | Next.js

API Reference

This page describes the Next.js adapter API, including functions to modify configuration and handle build completion.

`async modifyConfig(config, context)`

Called for any CLI command that loads the next.config.js file to allow modification of the configuration.

Parameters:

• config: The complete Next.js configuration object
• context.phase:…

`async onBuildComplete(context)`

Called after the build process completes with detailed information about routes and outputs.

Parameters:

• context.routing: Object containing Next.js routing phases and metadata -…

Parameters

Name	Type	Description	Default	Required
config	object	The complete Next.js configuration object		Yes
context.phase	string	The current build phase (see phases)		Yes
context.nextVersion	string	Version of Next.js being used		Yes
context.projectDir	string	Absolute path to the Next.js project directory		Yes
context.routing	object	Object containing Next.js routing phases and metadata		Yes
context.routing.beforeMiddleware	any	Routes executed before middleware (includes header and redirect handling)		Yes
context.routing.beforeFiles	any	Rewrite routes checked before filesystem route matching		Yes
context.routing.afterFiles	any	Rewrite routes checked after filesystem route matching		Yes
context.routing.dynamicRoutes	any	Dynamic route matching table		Yes
context.routing.onMatch	any	Routes applied after a successful match (for example immutable static asset cache headers)		Yes
context.routing.fallback	any	Final rewrite fallback routes		Yes
context.routing.shouldNormalizeNextData	boolean	Whether `/_next/data/<buildId>/...` URLs should be normalized during matching		Yes
context.routing.rsc	any	Route metadata used for React Server Components routing behavior		Yes
context.outputs	object	Detailed information about all build outputs organized by type		Yes
context.repoRoot	string	Absolute path to the detected repository root		Yes
context.distDir	string	Absolute path to the build output directory		Yes
context.config	object	The final Next.js configuration (with modifyConfig applied)		Yes
context.buildId	string	Unique identifier for the current build		Yes

Configuration

This page describes how to configure Next.js adapters by specifying the adapter module path via `adapterPath` in `next.config.js` or the `NEXT_ADAPTER_PATH` environment variable.

Configuration

To use an adapter, specify the path to your adapter module in adapterPath:

Alternatively NEXT_ADAPTER_PATH can be set to enable zero-config usage in deployment platforms.

/** @type {import('next').NextConfig} */
const nextConfig = {
  adapterPath: require.resolve('./my-adapter.js'),
}
 
module.exports = nextConfig

Parameters

Name	Type	Description	Default	Required
adapterPath	string	Path to the adapter module. Specify the path to your adapter module in `adapterPath`.		No
NEXT_ADAPTER_PATH	string	Environment variable that can be set to enable zero-config usage in deployment platforms.		No

Adapters: Output Types

Describes the `outputs` object structure exposed to Next.js adapters, including arrays for pages, API routes, app pages, app routes, prerenders, static files, and middleware, with TypeScript type…

Output Types

The outputs object contains arrays of build output types:

• outputs.pages: React pages from the pages/ directory
• outputs.pagesApi: API routes from pages/api/
• outputs.appPages: React…

Pages (`outputs.pages`)

React pages from the pages/ directory:

{
  type: 'PAGES'
  id: string           // Route identifier
  filePath: string     // Path to the built file
  pathname: string     // URL pathname
  sourcePage: string   // Original source file…

API Routes (`outputs.pagesApi`)

API routes from pages/api/:

{
  type: 'PAGES_API'
  id: string           // Route identifier
  filePath: string     // Path to the built file
  pathname: string     // URL pathname
  sourcePage: string   // Original relative…

App Pages (`outputs.appPages`)

React pages from the app/ directory:

{
  type: 'APP_PAGE'
  id: string           // Route identifier
  filePath: string     // Path to the built file
  pathname: string     // URL pathname. Includes .rsc suffix for RSC routes…

App Routes (`outputs.appRoutes`)

API and metadata routes from the app/ directory:

{
  type: 'APP_ROUTE'
  id: string           // Route identifier
  filePath: string     // Path to the built file
  pathname: string     // URL pathname
  sourcePage: string   // Original relative…

Prerenders (`outputs.prerenders`)

ISR-enabled routes and static prerenders:

{
  type: 'PRERENDER'
  id: string           // Route identifier
  pathname: string     // URL pathname
  parentOutputId: string  // ID of the source page/route
  groupId: number        //…

Prerender classification

routeType, response, and compute are emitted together on the primary response in a prerender group. Related RSC, data, and segment outputs omit these fields. Pages Router templates with…

Static Files (`outputs.staticFiles`)

Static assets and auto-statically optimized pages:

See Supporting immutable static assets for more information about immutableHash.

{
  type: 'STATIC_FILE'
  id: string // Unique identifier for this static file output
  filePath: string // Absolute filesystem path to the built file
  pathname: string // The routable URL pathname…

Middleware (`outputs.middleware`)

middleware.ts (.js/.ts) or proxy.ts (.js/.ts) function (if present):

{
  type: 'MIDDLEWARE'
  id: string           // Route identifier
  filePath: string     // Path to the built file
  pathname: string      // Always '/_middleware'
  sourcePage: string    // Always…

Parameters

Name	Type	Description	Default	Required
outputs.pages	Object[]	React pages from the `pages/` directory		Yes
outputs.pagesApi	Object[]	API routes from `pages/api/`		Yes
outputs.appPages	Object[]	React pages from the `app/` directory		Yes
outputs.appRoutes	Object[]	API and metadata routes from `app/`		Yes
outputs.prerenders	Object[]	ISR-enabled routes and static prerenders		Yes
outputs.staticFiles	Object[]	Static assets and auto-statically optimized pages		Yes
outputs.middleware	Object[]	Middleware function (if present)		Yes

Adapters: Routing Information

Describes the `routing` object available in `onBuildComplete`, including the route phases and common fields that make up deployment-ready routing information.

Routing Information

The routing object in onBuildComplete provides complete routing information with processed patterns ready for deployment:

routing.beforeMiddleware

Routes applied before middleware execution. These include generated header and redirect behavior.

routing.beforeFiles

Rewrite routes checked before filesystem route matching.

routing.afterFiles

Rewrite routes checked after filesystem route matching.

routing.dynamicRoutes

Dynamic matchers generated from route segments such as [slug] and catch-all routes.

routing.onMatch

Routes that apply after a successful match, such as immutable cache headers for hashed static assets.

routing.fallback

Final rewrite routes checked when earlier phases did not produce a match.

Common Route Fields

Each route entry can include:

• source: Original route pattern (optional for generated internal rules)
• sourceRegex: Compiled regex for matching requests
• destination: Internal destination…

Routing with @next/routing

Explains how to use the `@next/routing` package's `resolveRoutes()` function to reproduce Next.js route matching behavior with data from `onBuildComplete`.

Routing with @next/routing

You can use @next/routing to reproduce Next.js route matching behavior with data from onBuildComplete.

resolveRoutes() returns:

• middlewareResponded: true when middleware already sent a…

import { resolveRoutes } from '@next/routing'
 
const pathnames = [
  ...outputs.pages,
  ...outputs.pagesApi,
  ...outputs.appPages,
  ...outputs.appRoutes,
  ...outputs.staticFiles,
].map((output)…

Parameters

Name	Type	Description	Default	Required
url	URL	The request URL as a URL object.		Yes
buildId	string	The build ID for the deployment.		Yes
basePath	string	The base path of the Next.js application.	''	No
i18n	object	The i18n configuration object.		No
headers	Headers	The request headers as a Headers object.		Yes
requestBody	ReadableStream	The request body as a ReadableStream.		No
pathnames	string[]	An array of pathnames from the build output.		Yes
routes	object	The routing configuration from the build.		Yes
invokeMiddleware	async function	An async function to invoke middleware, returning a response object.		Yes

Runtime Integration

Describes the runtime behavior of Next.js server and cache interfaces, and how adapters interact with them, including handler context and PPR chain headers.

Overview

The Deployment Adapter API is a build-time interface. It tells your platform what was built and how to route requests. Runtime behavior (request handling, streaming, caching) is handled by…

Handler Context

When invoking entrypoints, adapters pass a ctx object to the Next.js handler. Key fields include:

• ctx.waitUntil: a function that accepts a promise. Use this to keep the serverless function…

PPR Chain Headers

In the prerenders output type, pprChain.headers contains the headers needed for the [resume…

create-next-app

The create-next-app CLI allows you to create a new Next.js application using the default template or an example from a public GitHub repository. It is the easiest way to get started with Next.js.

Basic usage

pnpm create next-app [project-name] [options]

Reference

The following options are available:

Examples

With the default template

To create a new app using the default template, run the following command in your terminal:

On installation, you'll see the following prompts:

If you choose to customize settings, you'll see the…

pnpm create next-app

What is your project named? my-app
Would you like to use the recommended Next.js defaults?
    Yes, use recommended defaults - TypeScript, ESLint, Tailwind CSS, App Router, AGENTS.md
    No, reuse…

Would you like to use TypeScript? No / Yes
Which linter would you like to use? ESLint / Biome / None
Would you like to use React Compiler? No / Yes
Would you like to use Tailwind CSS? No / Yes
Would…

Linter Options

ESLint : The traditional and most popular JavaScript linter. Includes Next.js-specific rules from @next/eslint-plugin-next.

Biome : A fast, modern linter and formatter that combines the…

With an official Next.js example

To create a new app using an official Next.js example, use the --example flag. For example:

You can view a list of all available examples along with setup instructions in the [Next.js…

pnpm create next-app --example [example-name] [your-project-name]

With any public GitHub example

To create a new app using any public GitHub example, use the --example option with the GitHub repository's URL. For example:

pnpm create next-app --example "https://github.com/.../" [your-project-name]

Parameters

Name	Type	Description	Default	Required
-h or --help	boolean	Show all available options		No
-v or --version	boolean	Output the version number		No
--no-*	boolean	Negate default options. E.g. --no-ts		No
--ts or --typescript	boolean	Initialize as a TypeScript project	True	No
--js or --javascript	boolean	Initialize as a JavaScript project		No
--tailwind	boolean	Initialize with Tailwind CSS config	True	No
--react-compiler	boolean	Initialize with React Compiler enabled		No
--eslint	boolean	Initialize with ESLint config		No
--biome	boolean	Initialize with Biome config		No
--no-linter	boolean	Skip linter configuration		No
--app	boolean	Initialize as an App Router project		No
--api	boolean	Initialize a project with only route handlers		No
--src-dir	boolean	Initialize inside a src/ directory		No
--turbopack	boolean	Force enable Turbopack in generated package.json	True	No
--webpack	boolean	Force enable Webpack in generated package.json		No
--import-alias <alias-to-configure>	string	Specify import alias to use	@/*	No
--empty	boolean	Initialize an empty project		No
--use-npm	boolean	Explicitly tell the CLI to bootstrap the application using npm		No
--use-pnpm	boolean	Explicitly tell the CLI to bootstrap the application using pnpm		No
--use-yarn	boolean	Explicitly tell the CLI to bootstrap the application using Yarn		No
--use-bun	boolean	Explicitly tell the CLI to bootstrap the application using Bun		No
-e or --example [name] [github-url]	string	An example to bootstrap the app with		No
--example-path <path-to-example>	string	Specify the path to the example separately		No
--reset-preferences	boolean	Explicitly tell the CLI to reset any stored preferences		No
--skip-install	boolean	Explicitly tell the CLI to skip installing packages		No
--disable-git	boolean	Explicitly tell the CLI to disable git initialization		No
--agents-md	boolean	Include AGENTS.md and CLAUDE.md to guide coding agents	True	No
--yes	boolean	Use previous preferences or defaults for all options		No

next CLI

The Next.js CLI allows you to develop, build, start your application, and more. It provides commands like dev, build, start, info, telemetry, typegen, upgrade, and experimental-analyze.

Basic Usage

The Next.js CLI allows you to develop, build, start your application, and more. Basic usage:

Good to know : With npm run, use -- before CLI flags so npm forwards them to next. This is…

pnpm 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	Starts Next.js in development mode with Hot Module Reloading, error reporting, and more.…

next dev options

next dev starts the application in development mode with Hot Module Reloading (HMR), error reporting, and more.

Good to know : Development builds output to .next/dev instead of .next.…

next build options

next build creates an optimized production build of your application. The output displays information about each route. For example:

Route (app)
┌ ○ /_not-found
└ ƒ /products/[id]
 
○…

Route (app)
┌ ○ /_not-found
└ ƒ /products/[id]
 
○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

next start options

next start starts the application in production mode. The application should be compiled with next build first.

The following options are available for the next start…

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. This information…

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:…

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…

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,…

# 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

next typegen
# or for a specific app
next typegen ./apps/web

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	…

next experimental-analyze options

next experimental-analyze analyzes your application's bundle output using Turbopack. This command helps you understand the size and composition of your bundles,…

pnpm next experimental-analyze

# 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

Debugging prerender errors

If you encounter prerendering errors during next build, you can pass the --debug-prerender flag to get more detailed output:

next build --debug-prerender

This enables several…

next build --debug-prerender

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…

# 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"

# Include route group folders in the…

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:

next dev -p 4000

Or using the…

next dev -p 4000

PORT=4000 next dev

Using HTTPS during development

For certain use cases like webhooks or authentication, you can use HTTPS to have a secure environment on localhost. Next.js can generate a…

next dev --experimental-https

next dev --experimental-https --experimental-https-key ./certificates/localhost-key.pem --experimental-https-cert ./certificates/localhost.pem

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…

next start --keepAliveTimeout 70000

Passing Node.js arguments

You can pass any node arguments to next commands. For example:

NODE_OPTIONS='--throw-deprecation' next
NODE_OPTIONS='-r esm'…

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…

# 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…

Version History

Version	Changes
v16.1.0	Add the next upgrade command
v16.1.0	Add the next experimental-analyze command
v16.0.0	The JS bundle size metrics have been…

Parameters

Name	Type	Description	Default	Required
global -h, --help	boolean	Shows all available options		No
global -v, --version	boolean	Outputs the Next.js version number		No
dev -h, --help	boolean	Show all available options.		No
dev [directory]	string	A directory in which to build the application. If not provided, current directory is used.		No
dev --turbopack	boolean	Force enable Turbopack (enabled by default). Also available as --turbo.		No
dev --webpack	boolean	Use Webpack instead of the default Turbopack bundler for development.		No
dev -p, --port	string	Specify a port number on which to start the application. Default: 3000, env: PORT	3000	No
dev -H, --hostname	string	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	0.0.0.0	No
dev --experimental-https	boolean	Starts the server with HTTPS and generates a self-signed certificate.		No
dev --experimental-https-key	string	Path to a HTTPS key file.		No
dev --experimental-https-cert	string	Path to a HTTPS certificate file.		No
dev --experimental-https-ca	string	Path to a HTTPS certificate authority file.		No
dev --experimental-upload-trace	string	Reports a subset of the debugging trace to a remote HTTP URL.		No
dev --experimental-cpu-prof	boolean	Enables CPU profiling using V8's inspector. Profiles are saved to .next-profiles/ on exit.		No
build -h, --help	boolean	Show all available options.		No
build [directory]	string	A directory on which to build the application. If not provided, the current directory will be used.		No
build --turbopack	boolean	Force enable Turbopack (enabled by default). Also available as --turbo.		No
build --webpack	boolean	Build using Webpack.		No
build -d, --debug	boolean	Enables a more verbose build output. With this flag enabled additional build output like rewrites, redirects, and headers will be shown.		No
build --profile	boolean	Enables production profiling for React.		No
build --no-lint	boolean	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
build --no-mangling	boolean	Disables mangling. This may affect performance and should only be used for debugging purposes.		No
build --experimental-app-only	boolean	Builds only App Router routes.		No
build --experimental-build-mode	string	Uses an experimental build mode. (choices: "compile", "generate", default: "default")	default	No
build --debug-prerender	boolean	Debug prerender errors in development.		No
build --debug-build-paths	string	Build only specific routes for debugging.		No
build --experimental-cpu-prof	boolean	Enables CPU profiling using V8's inspector. Profiles are saved to .next-profiles/ on exit.		No
start -h, --help	boolean	Show all available options.		No
start [directory]	string	A directory on which to start the application. If no directory is provided, the current directory will be used.		No
start -p, --port	string	Specify a port number on which to start the application. (default: 3000, env: PORT)	3000	No
start -H, --hostname	string	Specify a hostname on which to start the application (default: 0.0.0.0).	0.0.0.0	No
start --keepAliveTimeout	string	Specify the maximum amount of milliseconds to wait before closing the inactive connections.		No
start --experimental-cpu-prof	boolean	Enables CPU profiling using V8's inspector. Profiles are saved to .next-profiles/ on exit.		No
info -h, --help	boolean	Show all available options		No
info --verbose	boolean	Collects additional information for debugging.		No
telemetry -h, --help	boolean	Show all available options.		No
telemetry --enable	boolean	Enables Next.js' telemetry collection.		No
telemetry --disable	boolean	Disables Next.js' telemetry collection.		No
typegen -h, --help	boolean	Show all available options.		No
typegen [directory]	string	A directory on which to generate types. If not provided, the current directory will be used.		No
upgrade -h, --help	boolean	Show all available options.		No
upgrade [directory]	string	A directory with the Next.js application to upgrade. If not provided, the current directory will be used.		No
upgrade --revision	string	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.		No
upgrade --verbose	boolean	Show verbose output during the upgrade process.		No
experimental-analyze -h, --help	boolean	Show all available options.		No
experimental-analyze [directory]	string	A directory on which to analyze the application. If not provided, the current directory will be used.		No
experimental-analyze --no-mangling	boolean	Disables mangling. This may affect performance and should only be used for debugging purposes.		No
experimental-analyze --profile	boolean	Enables production profiling for React. This may affect performance.		No
experimental-analyze -o, --output	boolean	Write analysis files to disk without starting the server. Output is written to .next/diagnostics/analyze.		No
experimental-analyze --port	string	Specify a port number to serve the analyzer on. (default: 4000, env: PORT)	4000	No

Font Module

This page documents the Next.js Font Module (`next/font`), which automatically optimizes fonts, self-hosts font files, and provides built-in support for Google Fonts. It covers the API reference for…

Reference

The following table lists the available options for the font loader functions. The columns indicate which loader (font/google or font/local) each option applies to, the type, and whether it is…

src

The path of the font file as a string or an array of objects (with type Array<{path: string, weight?: string, style?: string}>) relative to the directory where the font loader function is…

weight

The font weight with the following possibilities:

• A string with possible values of the weights available for the specific font or a range of…

style

The font style with the following possibilities:

• A string value with…

subsets

The font subsets defined by an array of string values with the names of each subset you would like to be…

axes

Some variable fonts have extra axes that can be included. By default, only the font weight is included to keep the file size down. The possible values of axes depend on the specific font.

Used…

display

The font display with possible string values of…

preload

A boolean value that specifies whether the font should be preloaded or not. The default is true.

Used in next/font/google and…

fallback

The fallback font to use if the font cannot be loaded. An array of strings of fallback fonts with no default.

• Optional

Used in next/font/google and next/font/local

Examples:

• `fallback:…

adjustFontFallback

• For next/font/google: A boolean value that sets whether an automatic fallback font should be used to reduce Cumulative Layout Shift. The default is true.

• For…

variable

A string value to define the CSS variable name to be used if the style is applied with the CSS variable method.

Used in next/font/google and next/font/local

-…

declarations

An array of font face descriptor key-value pairs that define the generated @font-face further.

Used in next/font/local

-…

Examples

Google Fonts

To use a Google font, import it from next/font/google as a function. We recommend using variable fonts for the best performance and flexibility.

If you…

import { Inter } from 'next/font/google'
 
// If loading a variable font, you don't need to specify the font weight
const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
})
 
export default…

import { Roboto } from 'next/font/google'
 
const roboto = Roboto({
  weight: '400',
  subsets: ['latin'],
  display: 'swap',
})
 
export default function RootLayout({
  children,
}: {
  children:…

const roboto = Roboto({
  weight: ['400', '700'],
  style: ['normal', 'italic'],
  subsets: ['latin'],
  display: 'swap',
})

Specifying a subset

Google Fonts are automatically subset. This reduces the size of the font file and improves performance. You'll need to define which of these…

const inter = Inter({ subsets: ['latin'] })

Using Multiple Fonts

You can import and use multiple fonts in your application. There are two approaches you can take.

The first approach is to create a utility function that exports a font, imports it, and applies its…

import { Inter, Roboto_Mono } from 'next/font/google'
 
export const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
})
 
export const roboto_mono = Roboto_Mono({
  subsets: ['latin'],…

import { inter } from './fonts'
 
export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={inter.className}>
      <body>…

import { roboto_mono } from './fonts'
 
export default function Page() {
  return (
    <>
      <h1 className={roboto_mono.className}>My page</h1>
    </>
  )
}

import { Inter, Roboto_Mono } from 'next/font/google'
import styles from './global.css'
 
const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',
  display: 'swap',
})
 
const…

html {
  font-family: var(--font-inter);
}
 
h1 {
  font-family: var(--font-roboto-mono);
}

Local Fonts

Import next/font/local and specify the src of your local font file. We recommend using variable fonts for the best performance and flexibility.

If you…

import localFont from 'next/font/local'
 
// Font files can be colocated inside of `app`
const myFont = localFont({
  src: './my-font.woff2',
  display: 'swap',
})
 
export default function…

const roboto = localFont({
  src: [
    {
      path: './Roboto-Regular.woff2',
      weight: '400',
      style: 'normal',
    },
    {
      path: './Roboto-Italic.woff2',
      weight: '400',…

With Tailwind CSS

next/font integrates seamlessly with Tailwind CSS using CSS variables.

In the example below, we use the Inter…

import { Inter, Roboto_Mono } from 'next/font/google'
 
const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
})
 
const roboto_mono = Roboto_Mono({
  subsets:…

@import 'tailwindcss';
 
@theme inline {
  --font-sans: var(--font-inter);
  --font-mono: var(--font-roboto-mono);
}

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
    './app/**/*.{js,ts,jsx,tsx}',
  ],…

<p class="font-sans ...">The quick brown fox ...</p>
<p class="font-mono ...">The quick brown fox ...</p>

Applying Styles

You can apply the font styles in three ways:

• className
• style
• CSS Variables

className

Returns a read-only CSS className for the loaded font to be passed to an HTML element.

<p className={inter.className}>Hello, Next.js!</p>

CSS Variables

If you would like to set your styles in an external style sheet and specify additional options there, use the CSS variable method.

In addition to importing the font, also import the CSS file where…

import { Inter } from 'next/font/google'
import styles from '../styles/component.module.css'
 
const inter = Inter({
  variable: '--font-inter',
})

<main className={inter.variable}>
  <p className={styles.text}>Hello World</p>
</main>

.text {
  font-family: var(--font-inter);
  font-weight: 200;
  font-style: italic;
}

Using a font definitions file

Every time you call the localFont or Google font function, that font will be hosted as one instance in your application. Therefore, if you need to use the same font in multiple places, you should…

import { Inter, Lora, Source_Sans_3 } from 'next/font/google'
import localFont from 'next/font/local'
 
// define your variable fonts
const inter = Inter()
const lora = Lora()
// define 2 weights of…

import { inter, lora, sourceCodePro700, greatVibes } from '../styles/fonts'
 
export default function Page() {
  return (
    <div>
      <p className={inter.className}>Hello world using Inter…

{
  "compilerOptions": {
    "paths": {
      "@/fonts": ["./styles/fonts"]
    }
  }
}

import { greatVibes, sourceCodePro400 } from '@/fonts'

Preloading

When a font function is called on a page of your site, it is not globally available and preloaded on all routes. Rather, the font is only preloaded on the related routes based on the type of file…

Version Changes

The following table lists the version history for the Font Module.

Parameters

Name	Type	Description	Default	Required
src	String or Array of Objects	The path of the font file as a string or an array of objects (with type `Array<{path: string, weight?: string, style?: string}>`) relative to the directory where the font loader function is called.…		Yes
weight	String or Array	The font weight. A string with possible values of the weights available for the specific font or a range of values if it's a variable font. An array of weight values if the font is not a variable…		Yes
style	String or Array	The font style. A string value with default value of `'normal'`. An array of style values if the font is not a variable google font (applies to `next/font/google` only). Optional.	'normal'	No
subsets	Array of Strings	The font subsets defined by an array of string values with the names of each subset you would like to be preloaded. Fonts specified via `subsets` will have a link preload tag injected into the head…		No
axes	Array of Strings	Some variable fonts have extra `axes` that can be included. By default, only the font weight is included to keep the file size down. The possible values of `axes` depend on the specific font. Used in…		No
display	String	The font display property with possible string values of `'auto'`, `'block'`, `'swap'`, `'fallback'` or `'optional'` with default value of `'swap'`.	'swap'	No
preload	Boolean	A boolean value that specifies whether the font should be preloaded or not. The default is `true`.	true	No
fallback	Array of Strings	The fallback font to use if the font cannot be loaded. An array of strings of fallback fonts with no default.		No
adjustFontFallback	Boolean or String	For `next/font/google`: A boolean value that sets whether an automatic fallback font should be used to reduce Cumulative Layout Shift. The default is `true`. For `next/font/local`: A string or…	true (google) / 'Arial' (local)	No
variable	String	A string value to define the CSS variable name to be used if the style is applied with the CSS variable method.		No
declarations	Array of Objects	An array of font face descriptor key-value pairs that define the generated `@font-face` further. Used in `next/font/local`.		No

Form Component

The <Form> component extends the HTML <form> element to provide prefetching of loading UI, client-side navigation on submission, and progressive enhancement. It is useful for forms that update URL…

Overview

The <Form> component extends the HTML <form> element to provide prefetching of loading UI, client-side navigation on submission, and progressive enhancement. It's useful for forms…

import Form from 'next/form'
 
export default function Page() {
  return (
    <Form action="/search">
      {/* On submission, the input value will be appended to
          the URL, e.g.…

Reference

The behavior of the <Form> component depends on whether the action prop is passed a string or function.

• When action is a string, the <Form> behaves like a native HTML form that…

action (string) Props

When action is a string, the <Form> component supports the following props:

• action : The URL or path to navigate to when the form is submitted. An empty string "" will navigate to the…

action (function) Props

When action is a function, the <Form> component supports the following prop:

• action : The Server Action to be called when the form is submitted. See the [React…

Caveats

• formAction : Can be used in a <button> or <input type="submit"> fields to override the action prop. Next.js will perform a client-side navigation, however, this approach doesn't support…

Examples

Search form that leads to a search result page

You can create a search form that navigates to a search results page by passing the path as an action:

When the user updates the query input field and submits the form, the form data will be…

import Form from 'next/form'
 
export default function Page() {
  return (
    <Form action="/search">
      <input name="query" />
      <button type="submit">Submit</button>
    </Form>
  )
}

import { getSearchResults } from '@/lib/search'
 
export default async function SearchPage({
  searchParams,
}: {
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {…

export default function Loading() {
  return <div>Loading...</div>
}

'use client'
import { useFormStatus } from 'react-dom'
 
export default function SearchButton() {
  const status = useFormStatus()
  return (
    <button type="submit">{status.pending ?…

import Form from 'next/form'
import { SearchButton } from '@/ui/search-button'
 
export default function Page() {
  return (
    <Form action="/search">
      <input name="query" />…

Mutations with Server Actions

You can perform mutations by passing a function to the action prop.

After a mutation, it's common to redirect to the new resource. You can use the redirect…

import Form from 'next/form'
import { createPost } from '@/posts/actions'
 
export default function Page() {
  return (
    <Form action={createPost}>
      <input name="title" />
      {/* ... */}…

'use server'
import { redirect } from 'next/navigation'
 
export async function createPost(formData: FormData) {
  // Create a new post
  // ...
 
  // Redirect to the new post…

import { getPost } from '@/posts/data'
 
export default async function PostPage({
  params,
}: {
  params: Promise<{ id: string }>
}) {
  const { id } = await params
  const data = await getPost(id)…

Parameters

Name	Type	Description	Default	Required
action	string | function	The URL or path to navigate to when the form is submitted (string) or the Server Action to be called when the form is submitted (function). When a string, an empty string `""` navigates to the same…		Yes
replace	boolean	Replaces the current history state instead of pushing a new one to the browser's history stack. Only applies when `action` is a string. Default is `false`.	false	No
scroll	boolean	Controls the scroll behavior during navigation. Defaults to `true`, meaning it will scroll to the top of the new route and maintain scroll position for backwards/forwards navigation. Only applies…	true	No
prefetch	boolean	Controls whether the path should be prefetched when the form becomes visible in the user's viewport. Only applies when `action` is a string. Defaults to `true`.	true	No

Link Component

This page documents the Next.js `<Link>` component, a React component that extends the HTML `<a>` element to provide prefetching and client-side navigation between routes. It covers the component's…

Link Component

<Link> is a React component that extends the HTML <a> element to provide prefetching and client-side navigation between routes. It…

import Link from 'next/link'
 
export default function Page() {
  return <Link href="/dashboard">Dashboard</Link>
}

Reference

The following props can be passed to the <Link> component:

Prop	Example	Type	Required
href	href="/dashboard"	String or Object	Yes…

href (required)

The path or URL to navigate to.

import Link from 'next/link'
 
// Navigate to /about?name=test
export default function Page() {
  return (
    <Link
      href={{
        pathname: '/about',
        query: { name: 'test' },…

replace

Defaults to false. When true, next/link will replace the current history state instead of adding a new URL into the [browser's…

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/dashboard" replace>
      Dashboard
    </Link>
  )
}

scroll

Defaults to true. The default scrolling behavior of <Link> in Next.js is to maintain scroll position, similar to how browsers handle back and forwards navigation. When you navigate to a…

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/dashboard" scroll={false}>
      Dashboard
    </Link>
  )
}

prefetch

Prefetching happens when a <Link /> component enters the user's viewport (initially or through scroll). Next.js prefetches and loads the linked route (denoted by the href) and its data in the…

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/dashboard" prefetch={false}>
      Dashboard
    </Link>
  )
}

onNavigate

An event handler called during client-side navigation. The handler receives an event object that includes a preventDefault() method, allowing you to cancel the navigation if needed.

**Good to…

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link
      href="/dashboard"
      onNavigate={(e) => {
        // Only executes during SPA navigation…

transitionTypes

A list of transition types to apply to the navigation. These types are passed to React.addTransitionType inside the navigation transition,…

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/about" transitionTypes={['slide-in']}>
      About
    </Link>
  )
}

Examples

The following examples demonstrate how to use the <Link> component in different scenarios.

Linking to dynamic route segments

When linking to dynamic segments, you can use [template literals and…

import Link from 'next/link'
 
interface Post {
  id: number
  title: string
  slug: string
}
 
export default function PostList({ posts }: { posts: Post[] }) {
  return (
    <ul>…

Checking active links

You can use usePathname() to check if a link is active. For example, to add a class to the active link, you can check if the current pathname…

'use client'
 
import { usePathname } from 'next/navigation'
import Link from 'next/link'
 
export function Links() {
  const pathname = usePathname()
 
  return (
    <nav>
      <Link…

Scrolling to an `id`

If you'd like to scroll to a specific id on navigation, you can append your URL with a # hash link or just pass a hash link to the href prop. This is possible since <Link> renders to an <a>…

<Link href="/dashboard#settings">Settings</Link>
 
// Output
<a href="/dashboard#settings">Settings</a>

Replace the URL instead of push

The default behavior of the Link component is to push a new URL into the history stack. You can use the replace prop to prevent adding a new entry, as in the following example:

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/about" replace>
      About us
    </Link>
  )
}

Disable scrolling to the top of the page

The default scrolling behavior of <Link> in Next.js is to maintain scroll position, similar to how browsers handle back and forwards navigation. When you navigate to a new…

import Link from 'next/link'
 
export default function Page() {
  return (
    <Link href="/#hashid" scroll={false}>
      Disables scrolling to the top
    </Link>
  )
}

// useRouter
import { useRouter } from 'next/navigation'
 
const router = useRouter()
 
router.push('/dashboard', { scroll: false })

Scroll offset with sticky headers

Because Next.js skips sticky and fixed positioned elements when finding the scroll target, content may end up behind a sticky header after navigation. For example, if your layout has a sticky…

import './globals.css'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <header className="sticky top-0…

html {
  scroll-padding-top: 64px; /* Match the height of your sticky header */
}

Prefetching links in Proxy

It's common to use Proxy for authentication or other purposes that involve rewriting the user to a different page. In order for the <Link />…

import { NextResponse } from 'next/server'
 
export function proxy(request: Request) {
  const nextUrl = request.nextUrl
  if (nextUrl.pathname === '/dashboard') {
    if (request.cookies.authToken)…

'use client'
 
import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed' // Your auth hook
 
export default function Page() {
  const isAuthed = useIsAuthed()
  const path = isAuthed…

Blocking navigation

You can use the onNavigate prop to block navigation when certain conditions are met, such as when a form has unsaved changes. When you need to block navigation across multiple components in your…

'use client'
 
import { createContext, useState, useContext } from 'react'
 
interface NavigationBlockerContextType {
  isBlocked: boolean
  setIsBlocked: (isBlocked: boolean) => void
}
 
export…

'use client'
 
import { useNavigationBlocker } from '../contexts/navigation-blocker'
 
export default function Form() {
  const { setIsBlocked } = useNavigationBlocker()
 
  return (
    <form…

'use client'
 
import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'
 
interface CustomLinkProps extends React.ComponentProps<typeof Link> {
  children:…

'use client'
 
import { CustomLink as Link } from './custom-link'
 
export default function Nav() {
  return (
    <nav>
      <Link href="/">Home</Link>
      <Link href="/about">About</Link>…

import { NavigationBlockerProvider } from './contexts/navigation-blocker'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">…

import Nav from './components/nav'
import Form from './components/form'
 
export default function Page() {
  return (
    <div>
      <Nav />
      <main>
        <h1>Welcome to the Dashboard</h1>…

Version history

Version	Changes
v16.2.0	Add transitionTypes prop.
v15.4.0	Add auto as an alias to the default prefetch behavior.
v15.3.0	Add onNavigate API
…

Parameters

Name	Type	Description	Default	Required
href	String or Object	The path or URL to navigate to.		Yes
replace	Boolean	When `true`, `next/link` will replace the current history state instead of adding a new URL into the browser's history stack.	false	No
scroll	Boolean	The default scrolling behavior of `<Link>` in Next.js is to maintain scroll position. When `scroll={false}`, Next.js will not attempt to scroll to the first Page element.	true	No
prefetch	Boolean or null	Prefetch behavior depends on whether the route is static or dynamic. When `true`, the full route is prefetched. When `false`, prefetching never happens. When `null` or `'auto'`, the default behavior…	null	No
onNavigate	Function	An event handler called during client-side navigation. The handler receives an event object that includes a `preventDefault()` method, allowing you to cancel the navigation if needed.		No
transitionTypes	string[]	A list of transition types to apply to the navigation. These types are passed to `React.addTransitionType` inside the navigation transition, enabling `<ViewTransition>` components to apply different…		No

Script Component

API reference for the Next.js Script component (next/script), covering its props, loading strategies, event handlers, and version history.

Script Component

This API reference will help you understand how to use props available for the Script Component. For features and usage, please see the Optimizing Scripts page.

import Script from 'next/script'
 
export default function Dashboard() {
  return (
    <>
      <Script src="https://example.com/script.js" />
    </>
  )
}

Props

Here's a summary of the props available for the Script Component:

Prop	Example	Type	Required
src	src="http://example.com/script"	String	Required…

Required Props

The <Script /> component requires the following properties.

src

A path string specifying the URL of an external script. This can be either an absolute external URL or an internal path. The src property is required unless an inline script is used.

Optional Props

The <Script /> component accepts a number of additional properties beyond those which are required.

strategy

The loading strategy of the script. There are four different strategies that can be used:

• beforeInteractive: Load before any Next.js code and before any page hydration occurs. -…

beforeInteractive

Scripts that load with the beforeInteractive strategy are injected into the initial HTML from the server, downloaded before any Next.js module, and executed in the order they are placed.

Scripts…

import Script from 'next/script'
 
export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        {children}…

afterInteractive

Scripts that use the afterInteractive strategy are injected into the HTML client-side and will load after some (or all) hydration occurs on the page. This is the default strategy of the Script…

import Script from 'next/script'
 
export default function Page() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="afterInteractive" />
    </>
  )
}

lazyOnload

Scripts that use the lazyOnload strategy are injected into the HTML client-side during browser idle time and will load after all resources on the page have been fetched. This strategy should be…

import Script from 'next/script'
 
export default function Page() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="lazyOnload" />
    </>
  )
}

worker

Warning: The worker strategy is not yet stable and does not yet work with the App Router. Use with caution.

Scripts that use the worker strategy are off-loaded to a web worker in order to…

module.exports = {
  experimental: {
    nextScriptWorkers: true,
  },
}

import Script from 'next/script'
 
export default function Home() {
  return (
    <>
      <Script src="https://example.com/script.js" strategy="worker" />
    </>
  )
}

onLoad

Warning: onLoad does not yet work with Server Components and can only be used in Client Components. Further, onLoad can't be used with beforeInteractive – consider using onReady…

'use client'
 
import Script from 'next/script'
 
export default function Page() {
  return (
    <>
      <Script…

onReady

Warning: onReady does not yet work with Server Components and can only be used in Client Components.

Some third-party scripts require users to run JavaScript code after the script has…

'use client'
 
import { useRef } from 'react'
import Script from 'next/script'
 
export default function Page() {
  const mapRef = useRef()
 
  return (
    <>
      <div ref={mapRef}></div>…

onError

Warning: onError does not yet work with Server Components and can only be used in Client Components. onError cannot be used with the beforeInteractive loading strategy.

Sometimes it is…

'use client'
 
import Script from 'next/script'
 
export default function Page() {
  return (
    <>
      <Script
        src="https://example.com/script.js"
        onError={(e: Error) => {…

Version History

Version	Changes
v13.0.0	beforeInteractive and afterInteractive is modified to support app.
v12.2.4	onReady prop added.
v12.2.2	Allow next/script…

Parameters

Name	Type	Description	Default	Required
src	String	A path string specifying the URL of an external script. This can be either an absolute external URL or an internal path. The `src` property is required unless an inline script is used.		Yes
strategy	String	The loading strategy of the script. One of `beforeInteractive`, `afterInteractive`, `lazyOnload`, or `worker`.	afterInteractive	No
onLoad	Function	Executes JavaScript code after the script has finished loading. Only works with `afterInteractive` or `lazyOnload` strategies. Cannot be used with Server Components or `beforeInteractive`.		No
onReady	Function	Executes JavaScript code after the script's load event when it first loads and after every subsequent component re-mount. Cannot be used with Server Components.		No
onError	Function	Handles errors when a script fails to load. Cannot be used with Server Components or the `beforeInteractive` loading strategy.		No

adapterPath

Documentation for the Next.js adapterPath configuration option, which allows deployment platforms or build systems to integrate with the Next.js build process via adapters.

Overview

Next.js provides a built-in adapters API. It allows deployment platforms or build systems to integrate with the Next.js build process. For a full reference implementation, see the…

Configuration

To use an adapter, specify the path to your adapter module in adapterPath:

Alternatively NEXT_ADAPTER_PATH can be set to enable zero-config usage in deployment platforms.

/** @type {import('next').NextConfig} */
const nextConfig = {
  adapterPath: require.resolve('./my-adapter.js'),
}
 
module.exports = nextConfig

Adapters

For full adapter implementation details, use the dedicated Adapters section:

• Configuration
• [Creating an…

Creating an Adapter

See Creating an Adapter.

API Reference

See API Reference.

Testing Adapters

See Testing Adapters.

Routing with `@next/routing`

See Routing with @next/routing.

Implementing PPR in an Adapter

See Implementing PPR in an Adapter.

Runtime Integration

See Runtime Integration.

Invoking Entrypoints

See Invoking Entrypoints.

Output Types

See Output Types.

Routing Information

See Routing Information.

Use Cases

See Use Cases.

allowedDevOrigins

Describes the `allowedDevOrigins` config option in Next.js, which allows additional origins to request the dev server during development.

allowedDevOrigins

Next.js blocks cross-origin requests to dev-only assets and endpoints during development by default to prevent unauthorized access.

To configure a Next.js application to allow requests from origins…

module.exports = {
  allowedDevOrigins: ['local-origin.dev', '*.local-origin.dev'],
}

Parameters

Name	Type	Description	Default	Required
allowedDevOrigins	string[]	Sets additional origins that can request the dev server in development mode. Accepts exact hostnames and wildcard subdomains (e.g., 'local-origin.dev', '*.local-origin.dev').	[]	No

appDir

Documents the `appDir` configuration option in next.config.js, which enables the App Router. It is a legacy API, no longer needed as of Next.js 13.4.

appDir

This is a legacy API and no longer recommended. It's still supported for backward compatibility.

Good to know: This option is no longer needed as of Next.js 13.4. The App Router is now stable.

The…

assetPrefix

Explains how to configure the `assetPrefix` option in `next.config.js` to serve static assets from a CDN.

Set up a CDN

Attention: Deploying to Vercel automatically configures a global CDN for your Next.js project. You do not need to manually setup an Asset Prefix.

Good to know: Next.js 9.5+ added support for a…

// @ts-check
import { PHASE_DEVELOPMENT_SERVER } from 'next/constants'
 
export default (phase) => {
  const isDev = phase === PHASE_DEVELOPMENT_SERVER
  /**
   * @type {import('next').NextConfig}…

/_next/static/chunks/4b9b41aaa062cbbfeff4add70f256968c51ece5d.4d708494b3aed70c04f0.js

https://cdn.mydomain.com/_next/static/chunks/4b9b41aaa062cbbfeff4add70f256968c51ece5d.4d708494b3aed70c04f0.js

Parameters

Name	Type	Description	Default	Required
assetPrefix	string	The URL prefix to use for static assets when served from a CDN.	undefined	No

authInterrupts

Reference for the experimental authInterrupts option in next.config.js, which enables the forbidden and unauthorized APIs in a Next.js application.

authInterrupts

This feature is currently available in the canary channel and subject to change. Try it out by upgrading Next.js, and share your feedback on…

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  experimental: {
    authInterrupts: true,
  },
}

export default nextConfig

Parameters

Name	Type	Description	Default	Required
experimental.authInterrupts	boolean	Enables the use of the forbidden and unauthorized APIs in your application. While these functions are experimental, this option must be enabled to use them.		No

cacheComponents

This page documents the `cacheComponents` configuration flag in Next.js, which enables component and function-level caching using the `use cache` directive, and implements Partial Prerendering as the…

Usage

Cache Components enables component and function-level caching using the use cache directive. Data fetching is dynamic by default, and you choose what…

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  cacheComponents: true,
}
 
export default nextConfig

Navigation with Activity

When cacheComponents is enabled, Next.js uses React's <Activity> component to preserve component state during client-side navigation.

Rather than…

Version History

Version	Change
16.0.0	cacheComponents introduced. This flag controls the ppr, useCache, and dynamicIO flags as a single, unified configuration.

Learn more

[### Caching

Learn how to cache data and UI in Next.js](/docs/app/getting-started/caching)[### ISR with Cache Components

Learn how to prerender a subset of dynamic routes, serve App Shells for the…

next.config.js: cacheHandlers | Next.js

This page documents the `cacheHandlers` configuration in next.config.js, which lets you define custom cache storage implementations for `'use cache'` and `'use cache: remote'`. It covers handler…

cacheHandlers

The cacheHandlers configuration allows you to define custom cache storage implementations for 'use cache' and [`'use cache:…

When to use custom cache handlers

Most applications don't need custom cache handlers. The default in-memory cache works well in the typical use case.

Custom cache handlers are for advanced scenarios where you need to either…

Usage

To configure custom cache handlers:

• Define your cache handler in a separate file, see examples for implementation details.
• Reference the file path in your Next config file

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  cacheHandlers: {
    default: require.resolve('./cache-handlers/default-handler.js'),
    remote:…

Handler types

• default: Used by the 'use cache' directive
• remote: Used by the 'use cache: remote' directive

If you don't configure cacheHandlers, Next.js uses an in-memory LRU (Least Recently…

API Reference

A cache handler must implement the CacheHandler interface with the following methods:

get()

Retrieve a cache entry for the given cache key.

Parameter	Type	Description
cacheKey	string	The unique key for the cache entry.
softTags	string[]	…

get(cacheKey: string, softTags: string[]): Promise<CacheEntry | undefined>

const cacheHandler = {
  async get(cacheKey, softTags) {
    const entry = cache.get(cacheKey)
    if (!entry) return undefined
 
    // Check if expired
    const now = Date.now()
    if (now >…

set()

Store a cache entry for the given cache key.

Parameter	Type	Description
cacheKey	string	The unique key to store the entry under.
pendingEntry	…

set(cacheKey: string, pendingEntry: Promise<CacheEntry>): Promise<void>

const cacheHandler = {
  async set(cacheKey, pendingEntry) {
    // Wait for the entry to be ready
    const entry = await pendingEntry
 
    // Store in your cache system
    cache.set(cacheKey,…

refreshTags()

Called periodically before starting a new request to sync with external tag services.

This is useful if you're coordinating cache invalidation across multiple instances or services. For in-memory…

refreshTags(): Promise<void>

const cacheHandler = {
  async refreshTags() {
    // For in-memory cache, no action needed
    // For distributed cache, sync tag state from external service
  },
}

getExpiration()

Get the maximum revalidation timestamp for a set of tags.

Parameter	Type	Description
tags	string[]	Array of tags to check expiration for.

Returns:

• 0 if…

getExpiration(tags: string[]): Promise<number>

const cacheHandler = {
  async getExpiration(tags) {
    // Return 0 if not tracking tag revalidation
    return 0
 
    // Or return the most recent revalidation timestamp
    // return…

updateTags()

Called when tags are revalidated or expired.

Parameter	Type	Description
tags	string[]	Array of tags to update.
durations	{ expire?: number }	…

updateTags(tags: string[], durations?: { expire?: number }): Promise<void>

const cacheHandler = {
  async updateTags(tags, durations) {
    // Invalidate all cache entries with matching tags
    for (const [key, entry] of cache.entries()) {
      if (entry.tags.some((tag)…

CacheEntry Type

The CacheEntry object has the following structure:

| Property | Type | Description | | --- |…

interface CacheEntry {
  value: ReadableStream<Uint8Array>
  tags: string[]
  stale: number
  timestamp: number
  expire: number
  revalidate: number
}

Examples

Basic in-memory cache handler

Here's a minimal implementation using a Map for storage. This example demonstrates the core concepts, but for a production-ready implementation with LRU eviction, error handling, and tag…

const cache = new Map()
const pendingSets = new Map()
 
module.exports = {
  async get(cacheKey, softTags) {
    // Wait for any pending set operation to complete
    const pendingPromise =…

External storage pattern

For durable storage like Redis or a database, you'll need to serialize the cache entries. Here's a simple Redis example:

const { createClient } = require('redis')
 
const client = createClient({ url: process.env.REDIS_URL })
client.connect()
 
module.exports = {
  async get(cacheKey, softTags) {
    // Retrieve from…

Distributed Tag Coordination

When running multiple Next.js instances, tag invalidation must be coordinated across instances. The default in-memory handler only tracks tags locally, so calling revalidateTag() on one instance…

const { createClient } = require('redis')
 
const client = createClient({ url: process.env.REDIS_URL })
client.connect()
 
// Local cache of tag timestamps, synced via refreshTags
const…

Soft Tags

Soft tags are implicit tags that Next.js automatically generates based on the route path. For example, the route /blog/hello generates soft tags for /, /blog, /blog/hello, and their…

Handling Streams

The CacheEntry.value is a ReadableStream<Uint8Array>. When implementing a cache handler that stores entries externally, keep in…

Error Handling

Cache operations should be implemented defensively:

• set() failure: the response is still served to the user because set() is called asynchronously after the response stream is already…

Platform Support

Deployment Option	Supported
Node.js server	Yes
Docker container	Yes…

Version History

Version	Changes
v16.0.0	cacheHandlers introduced.

Related

View related API references.

• use cache — Learn how to use the "use cache" directive to cache data in your Next.js application.
• [use cache:…

Parameters

Name	Type	Description	Default	Required
cacheKey	string	The unique key for the cache entry.		Yes
softTags	string[]	Implicit tags derived from the route path. See Soft Tags for how to use them.		Yes
cacheKey	string	The unique key to store the entry under.		Yes
pendingEntry	Promise<CacheEntry>	A promise that resolves to the cache entry.		Yes
tags	string[]	Array of tags to check expiration for.		Yes
tags	string[]	Array of tags to update.		Yes
durations	{ expire?: number }	Optional expiration duration in seconds.		No
value	ReadableStream<Uint8Array>	The cached data as a stream.		Yes
tags	string[]	Cache tags (excluding soft tags).		Yes
stale	number	Duration in seconds for client-side staleness.		Yes
timestamp	number	When the entry was created (timestamp in milliseconds).		Yes
expire	number	How long the entry is allowed to be used (in seconds).		Yes
revalidate	number	How long until the entry should be revalidated (in seconds).		Yes

next.config.js: cacheLife | Next.js

Reference for the cacheLife option in next.config.js, which lets you define custom cache profiles for use with the cacheLife function and the use cache directive.

cacheLife

The cacheLife option allows you to define custom cache profiles when using the cacheLife function inside components or functions, and within the…

Usage

To define a profile, enable the cacheComponents flag and add the cache profile in the cacheLife object in the next.config.js…

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  cacheComponents: true,
  cacheLife: {
    blog: {
      stale: 3600, // 1 hour
      revalidate: 900, // 15 minutes…

import { cacheLife } from 'next/cache'
 
export async function getCachedData() {
  'use cache'
  cacheLife('blog')
  const data = await fetch('/api/data')
  return data
}

Reference

The configuration object has key values with the following format:

Property	Value	Description	Requirement
stale	number	Duration the…

Related

View related API references.

• use cache — Learn how to use the "use cache" directive to cache data in your Next.js application. -…

Parameters

Name	Type	Description	Default	Required
stale	number	Duration the client should cache a value without checking the server.		No
revalidate	number	Frequency at which the cache should refresh on the server; stale values may be served while revalidating.		No
expire	number	Maximum duration for which a value can remain stale before switching to dynamic. Must be longer than `revalidate`.		No

compress

This page describes the `compress` option in `next.config.js`, which controls gzip compression for rendered content and static files when using `next start` or a custom server.

compress

By default, Next.js uses gzip to compress rendered content and static files when using next start or a custom server. This is an optimization for applications that do not have compression…

Disabling compression

To disable compression, set the compress config option to false:

We do not recommend disabling compression unless you have compression configured on your server, as compression reduces…

module.exports = {
  compress: false,
}

Parameters

Name	Type	Description	Default	Required
compress	boolean	Enables or disables gzip compression for rendered content and static files when using `next start` or a custom server. Defaults to `true` unless compression is already configured via a custom server.	true	No

crossOrigin

Use the `crossOrigin` option to add a `crossOrigin` attribute in all `<script>` tags generated by the `next/script` component, and define how cross-origin requests should be handled.

crossOrigin

Use the crossOrigin option to add a crossOrigin attribute in all <script> tags generated by the…

module.exports = {
  crossOrigin: 'anonymous',
}

Options

• 'anonymous': Adds crossOrigin="anonymous" attribute.

• 'use-credentials': Adds…

Parameters

Name	Type	Description	Default	Required
crossOrigin	string	Adds a crossOrigin attribute to all script tags generated by next/script. Can be 'anonymous' or 'use-credentials'.		No

devIndicators

Configuration for the on-screen development indicator in Next.js, allowing you to set its position or hide it entirely.

devIndicators

devIndicators allows you to configure the on-screen indicator that gives context about the current route you're viewing during development. Open next.config.ts and set position to choose where…

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  devIndicators: {
    position: 'bottom-right', // 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
  },
}
 
export…

const nextConfig: NextConfig = {
  devIndicators: false,
}
 
export default nextConfig

Troubleshooting

Indicator not marking a route as static

If you expect a route to be static and the indicator has marked it as dynamic, it's likely the route has opted out of prerendering. You can confirm if a route is…

Route (app)
┌ ○ /_not-found
└ ƒ /products/[id]
 
○  (Static)   prerendered as static content
ƒ  (Dynamic)  server-rendered on demand

Version History

Version	Changes
v16.0.0	appIsrStatus, buildActivity, and buildActivityPosition options have been removed.
v15.2.0	Improved on-screen indicator with new…

Parameters

Name	Type	Description	Default	Required
devIndicators	object | false	Configuration for the on-screen development indicator. Set to `false` to hide it entirely.		No
position	'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'	Position of the indicator on the screen.	'bottom-left'	No

env

Describes the legacy `env` config option in next.config.js for adding environment variables to the JavaScript bundle, noting it's no longer recommended.

env

This is a legacy API and no longer recommended. It's still supported for backward compatibility.

Since the release of Next.js 9.4 we now have a more intuitive…

module.exports = {
  env: {
    customKey: 'my-value',
  },
}

function Page() {
  return <h1>The value of customKey is: {process.env.customKey}</h1>
}
 
export default Page

return <h1>The value of customKey is: {process.env.customKey}</h1>

return <h1>The value of customKey is: {'my-value'}</h1>

expireTime

Describes the `expireTime` configuration option in Next.js, which sets a custom stale-while-revalidate expire time for CDNs in the Cache-Control header for ISR pages.

expireTime

You can specify a custom stale-while-revalidate expire time for CDNs to consume in the Cache-Control header for ISR enabled pages.

Open next.config.js and add the expireTime config:

Now…

module.exports = {
  // one hour in seconds
  expireTime: 3600,
}

Parameters

Name	Type	Description	Default	Required
expireTime	number	Custom stale-while-revalidate expire time in seconds for CDNs to consume in the Cache-Control header for ISR enabled pages.		No

generateBuildId

Explains how to use the generateBuildId option in next.config.js to generate a consistent build ID for your Next.js application.

generateBuildId

Next.js generates an ID during next build to identify which version of your application is being served. The same build should be used and boot up multiple containers.

If you are rebuilding for…

module.exports = {
  generateBuildId: async () => {
    // This could be anything, using the latest git hash
    return process.env.GIT_HASH
  },
}

generateEtags

This page describes the `generateEtags` configuration option in `next.config.js`, which controls whether Next.js generates ETags for every page. It shows how to disable ETag generation for HTML pages.

generateEtags

Next.js will generate etags for every page by default. You may want to disable etag generation for HTML pages depending on your cache strategy.

Open…

module.exports = {
  generateEtags: false,
}

Parameters

Name	Type	Description	Default	Required
generateEtags	boolean	When set to false, disables ETag generation for HTML pages. Defaults to true.	true	No

next.config.js: headers

This page explains how to set custom HTTP headers on responses in Next.js using the `headers` key in `next.config.js`, covering path matching, regex, header/cookie/query matching, basePath/i18n…

headers

Headers allow you to set custom HTTP headers on the response to an incoming request on a given path.

To set custom HTTP headers you can use the headers key in next.config.js:

headers can be…

module.exports = {
  headers() {
    return [
      {
        source: '/about',
        headers: [
          {
            key: 'x-custom-header',
            value: 'my custom header value',…

Header Overriding Behavior

If two headers match the same path and set the same header key, the last header key will override the first. Using the below headers, the path /hello will result in the header x-hello being…

module.exports = {
  headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'x-hello',
            value: 'there',
          },
        ],…

Path Matching

Path matches are allowed, for example /blog/:slug will match /blog/first-post (no nested paths):

The pattern /blog/:slug matches /blog/first-post and /blog/post-1 but not a nested path…

module.exports = {
  headers() {
    return [
      {
        source: '/blog/:slug',
        headers: [
          {
            key: 'x-slug',
            value: ':slug', // Matched parameters can be…

Wildcard Path Matching

To match a wildcard path you can use * after a parameter, for example /blog/:slug* will match /blog/a/b/c/d/hello-world:

module.exports = {
  headers() {
    return [
      {
        source: '/blog/:slug*',
        headers: [
          {
            key: 'x-slug',
            value: ':slug*', // Matched parameters can…

Regex Path Matching

To match a regex path you can wrap the regex in parenthesis after a parameter, for example /blog/:slug(\d{1,}) will match /blog/123 but not /blog/abc:

The following characters (, ), {,…

module.exports = {
  headers() {
    return [
      {
        source: '/blog/:post(\\d{1,})',
        headers: [
          {
            key: 'x-post',
            value: ':post',
          },…

module.exports = {
  headers() {
    return [
      {
        // this will match `/english(default)/something` being requested
        source: '/english\\(default\\)/:slug',
        headers: […

Header, Cookie, and Query Matching

To only apply a header when header, cookie, or query values also match the has field or don't match the missing field can be used. Both the source and all has items must match and all…

module.exports = {
  headers() {
    return [
      // if the header `x-add-header` is present,
      // the `x-another-header` header will be applied
      {
        source: '/:path*',
        has:…

Headers with basePath support

When leveraging basePath support with headers each source is automatically prefixed with the basePath unless you add basePath: false…

module.exports = {
  basePath: '/docs',
 
  headers() {
    return [
      {
        source: '/with-basePath', // becomes /docs/with-basePath
        headers: [
          {
            key:…

Headers with i18n support

When leveraging i18n support with headers each source is automatically prefixed to handle the configured locales unless you add locale: false to the…

module.exports = {
  i18n: {
    locales: ['en', 'fr', 'de'],
    defaultLocale: 'en',
  },
 
  headers() {
    return [
      {
        source: '/with-locale', // automatically handles all locales…

Cache-Control

Next.js sets the Cache-Control header of public, max-age=31536000, immutable for truly immutable assets. It cannot be overridden. These immutable files contain a SHA-hash in the file name, so…

Options

CORS

Cross-Origin Resource Sharing (CORS) is a security feature that allows you to control which sites can access your resources. You can set the…

headers() {
    return [
      {
        source: "/api/:path*",
        headers: [
          {
            key: "Access-Control-Allow-Origin",
            value: "*", // Set your origin
          },…

X-DNS-Prefetch-Control

This header controls DNS prefetching, allowing browsers to proactively perform domain name resolution on external links,…

{
  key: 'X-DNS-Prefetch-Control',
  value: 'on'
}

Strict-Transport-Security

This header informs browsers it should only be accessed using HTTPS, instead of using HTTP. Using the configuration…

{
  key: 'Strict-Transport-Security',
  value: 'max-age=63072000; includeSubDomains; preload'
}

X-Frame-Options

This header indicates whether the site should be allowed to be displayed within an iframe. This can prevent against…

{
  key: 'X-Frame-Options',
  value: 'SAMEORIGIN'
}

Permissions-Policy

This header allows you to control which features and APIs can be used in the browser. It was previously named…

{
  key: 'Permissions-Policy',
  value: 'camera=(), microphone=(), geolocation=(), browsing-topics=()'
}

X-Content-Type-Options

This header prevents the browser from attempting to guess the type of content if the Content-Type header is not…

{
  key: 'X-Content-Type-Options',
  value: 'nosniff'
}

Referrer-Policy

This header controls how much information the browser includes when navigating from the current website (origin) to another.

{
  key: 'Referrer-Policy',
  value: 'origin-when-cross-origin'
}

Content-Security-Policy

Learn more about adding a Content Security Policy to your application.

Version History

Version	Changes
v13.3.0	missing added.
v10.2.0	has added.
v9.5.0	Headers added.

Parameters

Name	Type	Description	Default	Required
source	string	The incoming request path pattern.		Yes
headers	Array<{ key: string, value: string }>	An array of response header objects, with `key` and `value` properties.		Yes
basePath	false | undefined	If false the basePath won't be included when matching, can be used for external rewrites only.	undefined	No
locale	false | undefined	Whether the locale should not be included when matching.	undefined	No
has	Array<{ type: 'header' | 'cookie' | 'host' | 'query', key: string, value?: string | undefined }>	An array of has objects with the `type`, `key` and `value` properties. All must match for the header to be applied.		No
missing	Array<{ type: 'header' | 'cookie' | 'host' | 'query', key: string, value?: string | undefined }>	An array of missing objects with the `type`, `key` and `value` properties. All must not match for the header to be applied.		No

htmlLimitedBots

The `htmlLimitedBots` config allows you to specify a list of user agents that should receive blocking metadata instead of streaming metadata in Next.js.

htmlLimitedBots

The htmlLimitedBots config allows you to specify a list of user agents that should receive blocking metadata instead of [streaming…

import type { NextConfig } from 'next'
 
const config: NextConfig = {
  htmlLimitedBots: /MySpecialBot|MyAnotherSpecialBot|SimpleCrawler/,
}
 
export default config

Default list

Next.js includes a default list of HTML limited bots, including:

• Google crawlers (e.g. Mediapartners-Google, AdsBot-Google, Google-PageRenderer)
• Bingbot
• Twitterbot
• Slackbot

See the full…

const config: NextConfig = {
  htmlLimitedBots: /MySpecialBot|MyAnotherSpecialBot|SimpleCrawler/,
}
 
export default config

Disabling

To fully disable streaming metadata:

import type { NextConfig } from 'next'
 
const config: NextConfig = {
  htmlLimitedBots: /.*/,
}
 
export default config

Version History

Version	Changes
15.2.0	htmlLimitedBots option introduced.

Custom Next.js Cache Handler

Explains how to configure a custom cache handler in next.config.js to persist cached pages and data to durable storage or share cache across instances, including method signatures and image…

Custom Next.js Cache Handler

You can configure the Next.js cache location if you want to persist cached pages and data to durable storage, or share the cache across multiple containers or instances of your Next.js…

module.exports = {
  cacheHandler: require.resolve('./cache-handler.js'),
  cacheMaxMemorySize: 0, // disable default in-memory caching
}

API Reference

The cache handler can implement the following methods: get, set, revalidateTag, and resetRequestCache.

get()

The ctx parameter contains a kind property that indicates the type of cache entry being retrieved. Possible values include 'APP_PAGE', 'APP_ROUTE', 'PAGES', 'FETCH', and…

set()

The data object contains a kind property that indicates the type of cache entry. For image optimization, kind will be 'IMAGE' and the data will include properties like buffer, etag,…

revalidateTag()

Returns Promise<void>. Learn more about revalidating data or the revalidateTag()…

resetRequestCache()

This method resets the temporary in-memory cache for a single request before the next request.

Returns void.

Good to know:

• revalidatePath is a convenience layer on top of cache tags.…

Image Optimization Caching

The cacheHandler can also be used for caching optimized images from next/image. To enable this, set images.customCacheHandler to true in your next.config.js:

Good to know : This…

module.exports = {
  cacheHandler: require.resolve('./cache-handler.js'),
  images: {
    customCacheHandler: true,
  },
}

Platform Support

Deployment Option	Supported
Node.js server	Yes
Docker container	Yes…

Version History

Version	Changes
v16.2.0	cacheHandler support for image optimization caching.
v14.1.0	Renamed to cacheHandler and became stable.
v13.4.0	…

Parameters

Name	Type	Description	Default	Required
key	string	The key to the cached value (used in get).		Yes
ctx	object	Context including the cache entry kind (used in get).		Yes
key	string	The key to store the data under (used in set).		Yes
data	Data or null	The data to be cached (used in set).		Yes
ctx	{ tags: [] }	The cache tags provided (used in set).		Yes
tag	string or string[]	The cache tags to revalidate (used in revalidateTag).		Yes