adapterPath using require.resolve
When configuring adapterPath in next.config.js, use require.resolve() to specify the path to your adapter module file. This ensures the correct path is resolved relative to the configuration file.
Next.js · API reference · all subjects
config
577 notes in this subject, read out of this brain and free to use. This is page 1 of 10.
Next.js adapters API purpose
The Next.js adapters API allows deployment platforms or build systems to integrate with the Next.js build process by hooking into it with a custom adapter.
adapterPath configuration option
The adapterPath option in next.config.js specifies the path to a custom adapter module for Next.js. It accepts a string path to the adapter file. Example: adapterPath: require.resolve('./my-adapter.js'). Alternatively, the NEXT_ADAPTER_PATH environment variable can be set to enable zero-config usage in deployment platforms.
allowedDevOrigins config option
allowedDevOrigins is a configuration option in next.config.js that allows you to specify additional origins that can request the dev server during development. Next.js blocks cross-origin requests to dev-only assets and endpoints by default to prevent unauthorized access. By default, only requests from the hostname the server was initialized with (localhost by default) are allowed. Use allowedDevOrigins to permit requests from other origins.
allowedDevOrigins example with wildcards
The allowedDevOrigins config option accepts an array of origin strings. It supports wildcard patterns such as '*.local-origin.dev' to match multiple subdomains. Example: module.exports = { allowedDevOrigins: ['local-origin.dev', '*.local-origin.dev'] }
App directory automatically enables React Strict Mode
Using the app directory automatically enables React Strict Mode.
appDir config option no longer needed after Next.js 13.4
The appDir configuration option is no longer needed as of Next.js 13.4 because the App Router is now stable. Previously this option was used to enable the App Router in earlier versions.
authInterrupts config example in next.config.ts
To enable authInterrupts in a TypeScript config file, set the experimental.authInterrupts property to true. Example: ```ts import type { NextConfig } from 'next' const nextConfig: NextConfig = { experimental: { authInterrupts: true, }, } export default nextConfig ```
authInterrupts configuration option
The authInterrupts configuration option in next.config.js enables the use of forbidden and unauthorized APIs in your application. This is an experimental feature that must be explicitly enabled by setting experimental.authInterrupts to true in the config file.
authInterrupts config example in next.config.js
To enable authInterrupts in a JavaScript config file, set the experimental.authInterrupts property to true. Example: ```js module.exports = { experimental: { authInterrupts: true, }, } ```
basePath with next/image component
When using the next/image component, the basePath must be manually added in front of the src property. The src value should include the full path including the basePath prefix. For example, if basePath is '/docs', use src='/docs/me.png' to properly serve the image.
basePath config option
The basePath config option deploys a Next.js application under a sub-path of a domain. It is set in next.config.js with a string value like '/docs'. This value must be set at build time and cannot be changed without re-building, as it is inlined in the client-side bundles.
basePath configuration example
To set basePath to '/docs', add the following to next.config.js: module.exports = { basePath: '/docs', }
basePath automatic application in links
When using next/link or next/router, the basePath is automatically applied to links. For example, if basePath is set to '/docs', a link to '/about' will automatically become '/docs/about' in the HTML output. This means application links do not need to be changed when the basePath value changes.
What assetPrefix does not affect
The assetPrefix config covers only requests to /_next/static/. It does not influence files in the public folder. For public folder assets served over a CDN, you must introduce the prefix yourself. In the Pages Router, assetPrefix also does not affect /_next/data/ requests for getServerSideProps or getStaticProps pages, which always resolve against the main domain.
basePath vs assetPrefix for sub-paths
For hosting an application on a sub-path like /docs, use the basePath config option instead of a custom assetPrefix. The basePath option (available in Next.js 9.5+) is better suited for this use case than configuring a custom asset prefix.
assetPrefix with phase-based configuration
The assetPrefix config can be set conditionally based on the deployment phase. Use the PHASE_DEVELOPMENT_SERVER constant from 'next/constants' to check if the application is running in development mode. For example: assetPrefix: isDev ? undefined : 'https://cdn.mydomain.com' will only use the CDN prefix in production, not during development.
assetPrefix config option for CDN setup
The assetPrefix config option in next.config.mjs allows you to configure a CDN for your Next.js project. It automatically prefixes all JavaScript and CSS files loaded from the /_next/ path (.next/static/ folder) with the specified asset prefix URL. For example, with assetPrefix set to 'https://cdn.mydomain.com', a request to /_next/static/chunks/example.js becomes https://cdn.mydomain.com/_next/static/chunks/example.js. You should only upload the contents of .next/static/ to your CDN, not the rest of the .next/ folder.
Vercel automatically configures assetPrefix
When deploying to Vercel, the platform automatically configures a global CDN for your Next.js project. You do not need to manually set up an assetPrefix configuration.
cacheComponents implements Partial Prerendering by default
When cacheComponents is enabled, Partial Prerendering (PPR) is the default behavior in the App Router. The experimental.ppr configuration flag and experimental_ppr route segment configuration are no longer necessary and have been removed.
cacheComponents config flag
cacheComponents is a Next.js configuration flag that enables component and function-level caching using the 'use cache' directive. To enable it, set cacheComponents: true in next.config.ts.
cacheComponents version history
cacheComponents was introduced in version 16.0.0. It controls the ppr, useCache, and dynamicIO flags as a single, unified configuration.
cacheComponents prerendering behavior
When cacheComponents is enabled, Next.js prerenders a static HTML shell that is served immediately while dynamic content streams in when ready. This allows mixing static and dynamic content within a single route.
cacheComponents requires Node.js runtime
The cacheComponents feature requires the Node.js runtime. Routes using the deprecated 'runtime = edge' export must be migrated, and other server-side JavaScript runtimes are not guaranteed to work.
cacheComponents migration from experimental features
If previously using experimental.useCache or experimental.dynamicIO, developers should migrate using the Version 16 upgrade guide. The experimental PPR configuration flag and experimental_ppr route segment configuration are no longer necessary when using cacheComponents.
cacheComponents and React Activity component
When cacheComponents is enabled, Next.js uses React's Activity component to preserve component state during client-side navigation. Previous routes are set to Activity mode 'hidden' instead of being unmounted, keeping component state intact when users navigate back.
Activity mode effects and state behavior
When a route is in Activity mode 'hidden', component state is preserved, effects are cleaned up when hidden, and effects are recreated when the route becomes visible again. Next.js uses heuristics to keep recently visited routes 'hidden' while older routes are removed from the DOM to prevent excessive growth.
cacheComponents enabled features
When cacheComponents is enabled, the following become available: the 'use cache' directive, the cacheLife function used with 'use cache', and the cacheTag function.
Data fetching default with cacheComponents
With cacheComponents enabled, data fetching is dynamic by default. Developers explicitly choose what to cache at the page, component, or function level using the 'use cache' directive.
When to disable compression
Disabling compression is useful when you have compression configured on your server and want to use a different algorithm. For example, you might disable Next.js compression to allow nginx to handle compression using brotli instead of gzip.
compress option recommendation
Disabling compression is not recommended unless you have compression configured on your server, as compression reduces bandwidth usage and improves application performance.
compress option server target requirement
Next.js gzip compression only works with the server target.
compress config option example
module.exports = { compress: false, }
How to disable compression
To disable compression, set the compress config option to false in next.config.js.
How to check if compression is enabled
You can check if compression is enabled and which algorithm is used by looking at the Accept-Encoding header (browser accepted options) and Content-Encoding header (currently used) in the response.
compress config option does not override existing server compression
If compression is already configured in your application via a custom server, Next.js will not add compression.
compress config option default behavior
By default, Next.js uses gzip to compress rendered content and static files when using 'next start' or a custom server. This compression is applied as an optimization for applications that do not have compression already configured.
crossOrigin config: 'use-credentials' option
Setting crossOrigin to 'use-credentials' adds crossOrigin="use-credentials" attribute to script tags. This allows scripts to be fetched with credentials.
crossOrigin config example
Example of setting crossOrigin in next.config.js: module.exports = { crossOrigin: 'anonymous', }
crossOrigin config: 'anonymous' option
Setting crossOrigin to 'anonymous' adds crossOrigin="anonymous" attribute to script tags. This allows scripts to be fetched without credentials.
crossOrigin config option
The crossOrigin option in next.config.js adds a crossOrigin attribute to all <script> tags generated by the next/script component. This controls how cross-origin requests should be handled.
cacheLife requires cacheComponents flag
To use cacheLife profiles, you must first enable the cacheComponents flag in next.config.js.
cacheLife() usage in component with use cache
Example of using a custom cacheLife profile in a Server Action: ```tsx import { cacheLife } from 'next/cache' export async function getCachedData() { 'use cache' cacheLife('blog') const data = await fetch('/api/data') return data } ```
cacheLife blog profile example
Example of defining a custom 'blog' cache profile in next.config.ts: ```ts import type { NextConfig } from 'next' const nextConfig: NextConfig = { cacheComponents: true, cacheLife: { blog: { stale: 3600, // 1 hour revalidate: 900, // 15 minutes expire: 86400, // 1 day }, }, } export default nextConfig ```
cacheLife stale property meaning
The stale property in a cacheLife profile specifies the duration in seconds that the client should cache a value without checking the server.
cacheLife config reference table
The cacheLife configuration object accepts the following properties: | Property | Type | Description | Requirement | |----------|------|-------------|--------------| | stale | number | Duration in seconds the client should cache a value without checking the server. | Optional | | revalidate | number | Frequency in seconds at which the cache should refresh on the server; stale values may be served while revalidating. | Optional | | expire | number | Maximum duration in seconds for which a value can remain stale before switching to dynamic. | Optional - Must be longer than revalidate | Built-in profile names that can be overridden: default, seconds, minutes, hours, days, weeks, max.
cacheLife revalidate property meaning
The revalidate property in a cacheLife profile specifies the frequency in seconds at which the cache should refresh on the server. Stale values may be served while revalidation occurs.
cacheLife expire property meaning and constraint
The expire property in a cacheLife profile specifies the maximum duration in seconds for which a value can remain stale before switching to dynamic rendering. The expire value must be longer than the revalidate value.
cacheLife config option overview
The cacheLife option in next.config.js allows you to define custom cache profiles for use with the cacheLife() function and use cache directive. Cache profiles are objects containing stale, revalidate, and expire properties, each specified in seconds.
devIndicators configuration example
import type { NextConfig } from 'next' const nextConfig: NextConfig = { devIndicators: { position: 'bottom-right', // 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' }, } export default nextConfig
Reasons a route opts out of prerendering
A route may opt out of prerendering and become dynamic for two reasons: the presence of Request-time APIs which rely on request information, or an uncached data request such as a call to an ORM or database driver. When a route cannot be statically rendered, consider using `loading.js` or `<Suspense />` to leverage streaming.
Static and dynamic route indicators in build output
When running `next build --debug`, the build output displays route prerendering status with symbols: a `○` symbol indicates a static (prerendered) route, and a `ƒ` symbol indicates a dynamic (server-rendered on demand) route. Static routes are prerendered as static content, while dynamic routes are server-rendered on demand.
devIndicators version history
In v16.0.0, the `appIsrStatus`, `buildActivity`, and `buildActivityPosition` options were removed. In v15.2.0, the on-screen indicator was improved with a new `position` option, and the `appIsrStatus`, `buildActivity`, and `buildActivityPosition` options were deprecated. In v15.0.0, a static on-screen indicator was added with the `appIsrStatus` option.
devIndicators position configuration option
The `devIndicators` config in next.config.ts controls the on-screen indicator shown during development that indicates whether the current route is static or dynamic. The `position` option accepts the values 'bottom-left', 'bottom-right', 'top-left', or 'top-right'. The default position is 'bottom-left'. To hide the indicator entirely, set `devIndicators` to `false`. When disabled, Next.js will still surface compile and runtime errors.
devIndicators disable example
const nextConfig: NextConfig = { devIndicators: false, } export default nextConfig
deploymentId in rolling deployments
During rolling deployments, some server instances may be running a new version while others run the old version. Setting a consistent deploymentId per deployment ensures clients always request assets from a matching deployment version, mismatches trigger a full reload to fetch correct assets, and Server Functions work correctly across deployment boundaries.
deploymentId in multi-server environments
When running multiple instances of a Next.js application behind a load balancer, all instances for the same deployment should use the same deploymentId. Example: module.exports = { deploymentId: process.env.DEPLOYMENT_VERSION || process.env.GIT_SHA, }
deploymentId config option
The deploymentId option allows you to set an identifier for your deployment. This identifier is used for version skew protection and cache busting during rolling deployments. It can be configured in next.config.js as: module.exports = { deploymentId: 'my-deployment-id', }
deploymentId mismatch behavior
When the client detects a mismatch between its deployment ID and the server's via the response header, it triggers a hard navigation (full page reload) instead of a client-side navigation. This ensures users always receive assets and Server Functions from a consistent deployment version.
deploymentId query parameter not used for routing
Next.js does not read the ?dpl= query parameter on incoming requests. The query parameter is for cache busting (ensuring browsers and CDNs fetch fresh assets), not for routing. If you need version-aware routing, you should consult your hosting provider or CDN's documentation for implementing deployment-based routing.