When to disable turbopackFileSystemCacheForBuild
If your build environment never preserves .next/cache between builds, set turbopackFileSystemCacheForBuild to false to skip writing a cache that will not be read and waste resources.
Next.js · API reference · all subjects
config
577 notes in this subject, read out of this brain and free to use. This is page 6 of 10.
turbopackFileSystemCacheForBuild option
turbopackFileSystemCacheForBuild (default: true) caches Turbopack's work for next build in .next/cache/turbopack. Subsequent builds start warm. Set to false to opt out of caching for builds. Build caching only works when the .next/cache directory is preserved between builds.
Build cache directory location and preservation
The build cache lives in .next/cache. Builds only get faster when that directory is restored before each build. In self-hosted builds, reuse the same working directory between builds. In containerized builds, explicitly cache or mount the .next/cache directory. For CI providers, configure build caching for .next/cache.
turbopackFileSystemCache config overview
Turbopack FileSystem Cache enables Turbopack to reduce work across next dev or next build commands. When enabled, Turbopack saves and restores data under the .next directory between runs, which speeds up subsequent builds and dev sessions. Two separate options control the cache: one for next dev and one for next build, both enabled by default.
turbopackFileSystemCacheForDev option
turbopackFileSystemCacheForDev (default: true) caches Turbopack's work for next dev in .next/dev/cache/turbopack. Restarting the dev server reuses the previous compilation. Set to false to opt out of caching for development.
taint config syntax
In next.config.ts: import type { NextConfig } from 'next'; const nextConfig: NextConfig = { experimental: { taint: true, }, }; export default nextConfig. In next.config.js: const nextConfig = { experimental: { taint: true, }, }; module.exports = nextConfig.
taint config option
The taint option enables support for experimental React APIs for tainting objects and values to prevent sensitive data from being accidentally passed to the client. Set taint to true in the experimental configuration object in next.config.ts or next.config.js. When enabled, you can use experimental_taintObjectReference and experimental_taintUniqueValue from React. Activating this flag also enables the React experimental channel for the app directory.
turbopack.ignoreIssue basic example
Here is a basic example configuration: ```ts import type { NextConfig } from 'next' const nextConfig: NextConfig = { turbopack: { ignoreIssue: [ { path: '**/vendor/**', }, ], }, } export default nextConfig ```
turbopack.ignoreIssue path field stability note
Issue titles and descriptions may change between Turbopack versions. The `path` field is generally stable but is not guaranteed to remain consistent for all issue types. When possible, prefer using more specific `path` patterns over `title` or `description` matching.
turbopack.ignoreIssue version history
`turbopack.ignoreIssue` was introduced in v16.2.0.
turbopack.ignoreIssue multiple rules example
You can specify multiple rules to suppress different issues: ```js module.exports = { turbopack: { ignoreIssue: [ { path: '**/vendor/**' }, { path: '**/legacy/**', title: 'Module not found' }, { path: /generated\//, description: /expected identifier/ }, ], }, } ```
turbopack.ignoreIssue config option
The `turbopack.ignoreIssue` option in next.config.js allows you to filter out specific Turbopack errors and warnings so they do not appear in the CLI output or the error overlay. This is useful for suppressing known warnings that do not affect your application, such as intentionally unresolved optional dependencies. This option is only available when using Turbopack (`next dev --turbopack`).
turbopack.ignoreIssue rule structure
Each rule in the `ignoreIssue` array is an object with the following fields: `path` (string | RegExp, required) matches against the file path of the issue; `title` (string | RegExp, optional) matches against the issue title; `description` (string | RegExp, optional) matches against the issue description. An issue is suppressed when it matches the `path` and all other specified fields in a rule. If only `path` is provided, any issue from a matching file is suppressed.
turbopack.ignoreIssue path field patterns
The `path` field accepts a glob pattern when a string or a regular expression that matches against the file path where the issue originated. Examples: `'**/vendor/**'` (glob pattern for any file under vendor/), `/node_modules\/legacy-lib/` (RegExp for files matching a pattern).
turbopack.ignoreIssue title field matching
The `title` field accepts an exact string match when a string or a regular expression that matches against the issue title. Example: specifying `title: 'Module not found'` will match issues with that exact title, or `title: /some-pattern/` will match issues whose title contains that pattern.
turbopack.ignoreIssue description field matching
The `description` field accepts an exact string match when a string or a regular expression that matches against the issue description. Example: specifying `description: /Cannot find module 'optional-dep'/` will match issues whose description matches that pattern.
turbopack.ignoreIssue optional dependencies example
To suppress warnings for optional dependencies when using `try/catch` around an optional `require()` call: ```ts import type { NextConfig } from 'next' const nextConfig: NextConfig = { turbopack: { ignoreIssue: [ { path: '**/lib/optional-feature/**', title: 'Module not found', }, ], }, } export default nextConfig ```
turbopackLocalPostcssConfig config option
The turbopackLocalPostcssConfig option in next.config.js changes how Turbopack resolves postcss.config.js files. This option is only relevant when using Turbopack (next dev or next build). It is located under the experimental configuration object.
turbopackLocalPostcssConfig enabled behavior
When turbopackLocalPostcssConfig is true, Turbopack searches for postcss.config.js starting from the CSS file's own directory first, then falls back to the project root. The config resolution order is: CSS file's directory → project root. This means per-directory configs take precedence over the root config.
turbopackLocalPostcssConfig usage example
To enable turbopackLocalPostcssConfig, add it to next.config.ts or next.config.js: TypeScript: ```ts import type { NextConfig } from 'next' const nextConfig: NextConfig = { experimental: { turbopackLocalPostcssConfig: true, }, } export default nextConfig ``` JavaScript: ```js /** @type {import('next').NextConfig} */ const nextConfig = { experimental: { turbopackLocalPostcssConfig: true, }, } module.exports = nextConfig ```
turbopackLocalPostcssConfig version history
turbopackLocalPostcssConfig was introduced in version v16.3.0.
turbopackMemoryEviction released in v16.3.0
turbopackMemoryEviction was released as experimental in Next.js version 16.3.0.
turbopackMemoryEviction config option
turbopackMemoryEviction controls whether Turbopack reclaims memory while the persistent FileSystem cache is enabled. After Turbopack writes a snapshot of its cache to disk, it can evict the in-memory copies of that data and reload them from disk on demand. This option only has an effect in 'next dev' sessions when the FileSystem Cache is enabled, since eviction relies on data already being persisted to disk. It is experimental and under active development.
turbopackMemoryEviction option values: false, auto, full
turbopackMemoryEviction has three options: false (never evict, cached data stays in memory for the lifetime of the process), 'auto' (default, evict after a snapshot only once enough memory has been allocated since the last eviction to make it worthwhile, leverages thresholds and memory pressure feedback from the operating system), and 'full' (evict all possible data from memory every time we save to disk).
turbopackMemoryEviction TypeScript example
The following example shows how to configure turbopackMemoryEviction in a TypeScript next.config.ts file: import type { NextConfig } from 'next' const nextConfig: NextConfig = { experimental: { turbopackMemoryEviction: 'auto', }, } export default nextConfig
turbopackMemoryEviction JavaScript example
The following example shows how to configure turbopackMemoryEviction in a JavaScript next.config.js file: /** @type {import('next').NextConfig} */ const nextConfig = { experimental: { turbopackMemoryEviction: 'auto', }, } module.exports = nextConfig
staticGenerationRetryCount config option
staticGenerationRetryCount is an experimental config option that specifies the number of times to retry a failed page generation before failing the build. It is set within the experimental object in next.config.ts or next.config.js. The default value shown in the example is 1.
staticGenerationMaxConcurrency config option
staticGenerationMaxConcurrency is an experimental config option that specifies the maximum number of pages to be processed per worker. It is set within the experimental object in next.config.ts or next.config.js. The default value shown in the example is 8.
staticGenerationMinPagesPerWorker config option
staticGenerationMinPagesPerWorker is an experimental config option that specifies the minimum number of pages to be processed before starting a new worker. It is set within the experimental object in next.config.ts or next.config.js. The default value shown in the example is 25.
staticGeneration experimental config options structure
The staticGeneration options are configured within the experimental object in next.config.ts or next.config.js. All three options (staticGenerationRetryCount, staticGenerationMaxConcurrency, staticGenerationMinPagesPerWorker) are set as properties of the experimental object.
staticGeneration config example
```ts import type { NextConfig } from 'next' const nextConfig: NextConfig = { experimental: { staticGenerationRetryCount: 1, staticGenerationMaxConcurrency: 8, staticGenerationMinPagesPerWorker: 25, }, } export default nextConfig ``` This example shows how to configure the staticGeneration options in TypeScript using next.config.ts.
supportsImmutableAssets example configuration
To disable immutable static assets in next.config.js: ```js /** @type {import('next').NextConfig} */ const nextConfig = { supportsImmutableAssets: false, } module.exports = nextConfig ```
supportsImmutableAssets skew protection URL format
When immutable static assets are not used (skew protection enabled), asset URLs include a deployment-specific query parameter: GET https://foo.com/_next/static/chunks/0d_ks0ow7ur6m.js?dpl=<unique-deployment-id>
supportsImmutableAssets deployment optimization benefit
Using immutable static assets allows unchanged static assets to be skipped when uploading files during subsequent deployments, and lets browsers cache those assets indefinitely without re-downloading them after each new deployment.
supportsImmutableAssets version history
The supportsImmutableAssets feature was added in Next.js v16.3.0.
supportsImmutableAssets warning about breaking deployments
Enabling supportsImmutableAssets (or leaving it enabled) when your provider or adapter does not support it can result in broken deployments.
supportsImmutableAssets config option
The supportsImmutableAssets configuration option controls whether Next.js omits the deployment-specific query parameter (?dpl=<unique-deployment-id>) from static asset URLs. When enabled (default, if adapter supports it), immutable assets are served from the /_next/static/immutable/ path without the dpl query parameter, allowing browsers to cache them indefinitely. When disabled by setting supportsImmutableAssets to false, the dpl query parameter is included on all static assets. This option is primarily for adapter authors; app developers should only modify it when troubleshooting adapter-specific issues.
supportsImmutableAssets default behavior
If an adapter has enabled support for immutable static assets, Next.js will automatically use them by default. The supportsImmutableAssets config option allows opting out of this behavior. If an adapter has not enabled this feature, the supportsImmutableAssets option has no effect.
supportsImmutableAssets immutable asset URL format
When immutable static assets are supported and enabled, asset URLs follow the pattern: GET https://foo.com/_next/static/immutable/chunks/0d_ks0ow7ur6m.js (without the ?dpl query parameter).
turbopackRustReactCompiler only works with Turbopack
The `experimental.turbopackRustReactCompiler` option is only supported with Turbopack. Using it with webpack will throw an error.
turbopackRustReactCompiler requires reactCompiler enabled
The `experimental.turbopackRustReactCompiler` option requires the `reactCompiler` option to be enabled first. It selects which implementation runs, but does not turn the compiler on by itself.
turbopackRustReactCompiler config option
The `experimental.turbopackRustReactCompiler` option enables the native Rust version of the React Compiler, running it directly inside Turbopack as native code instead of through Node.js. This typically results in a noticeable performance improvement compared to the standard Babel version.
turbopackRustReactCompiler does not require babel-plugin-react-compiler
When `experimental.turbopackRustReactCompiler` is enabled, you do not need to install `babel-plugin-react-compiler`. The Rust compiler runs natively inside Turbopack.
turbopackRustReactCompiler configuration example
To enable the Rust React Compiler with Turbopack, set both `reactCompiler: true` and `experimental.turbopackRustReactCompiler: true` in next.config.ts or next.config.js.
turbopackRustReactCompiler introduced in v16.3.0
The experimental `turbopackRustReactCompiler` option was introduced in Next.js version 16.3.0.
typedRoutes configuration example
To enable typedRoutes, add the following to next.config.js: ```js filename="next.config.js" /** @type {import('next').NextConfig} */ const nextConfig = { typedRoutes: true, } module.exports = nextConfig ```
typedRoutes config option
The typedRoutes configuration option enables support for statically typed links in Next.js. This feature requires TypeScript to be used in your project. It is set as a boolean in next.config.js. The typedRoutes option has been marked as stable and should be used instead of the experimental.typedRoutes option.
tsconfigPath option
The tsconfigPath option specifies the path to a custom tsconfig.json file for builds or tooling. The default value is 'tsconfig.json'. This allows pointing to an alternative TypeScript configuration file like 'tsconfig.build.json'.
typescript config example
Example configuration showing both typescript options in next.config.js: module.exports = { typescript: { ignoreBuildErrors: false, tsconfigPath: 'tsconfig.json', } }
typescript config option structure
The typescript option in next.config.js configures TypeScript behavior. It accepts two properties: ignoreBuildErrors (boolean, default false) and tsconfigPath (string, default 'tsconfig.json').
ignoreBuildErrors option
The ignoreBuildErrors option allows production builds to complete even with TypeScript errors present. When set to true, it completely bypasses TypeScript type checking rather than suppressing errors. This means TypeScript is not run at all during the build. The default value is false, which causes next build to fail when TypeScript errors are present. If disabled, type checks should be run as part of the build or deploy process for safety.
ignoreBuildErrors danger and use case
Setting ignoreBuildErrors to true is a dangerous practice because it completely skips the TypeScript type checking step during builds. It is only appropriate when type checks are guaranteed to run as part of a separate build or deploy process.
URL imports with asset URL constructor
You can use the URL constructor with import.meta.url to create URLs from external assets: const logo = new URL('https://example.com/assets/file.txt', import.meta.url); This will resolve to a path like '/_next/static/media/file.a9727b5d.txt'
urlImports experimental config option
The urlImports configuration option is an experimental feature that allows importing modules directly from external URLs instead of from the local disk. To enable it, add an array of allowed URL prefixes to next.config.js under experimental.urlImports. Example: module.exports = { experimental: { urlImports: ['https://example.com/assets/', 'https://cdn.skypack.dev'] } }
URL imports usage and scope
URL imports can be used everywhere normal package imports can be used. After configuring allowed domains in next.config.js, you can import modules directly from URLs using standard import syntax, such as: import { a, b, c } from 'https://example.com/assets/some/module.js'
next.lock directory for URL imports
When using URL imports, Next.js creates a next.lock directory containing a lockfile and fetched assets. This directory must be committed to Git and not ignored by .gitignore. During 'next dev', newly discovered URL imports are downloaded and added to the lockfile. During 'next build', only the lockfile is used and no network requests are typically needed. Resources with 'Cache-Control: no-cache' headers receive a 'no-cache' entry in the lockfile and are fetched from the network on each build. An outdated lockfile will cause the build to fail.
URL imports security model
URL imports are designed with security as the top priority. An experimental flag requires explicitly allowing domains you accept URL imports from. The feature is being designed to limit URL imports to execute in the browser sandbox using the Edge Runtime.
URL imports from Skypack example
You can import packages from Skypack CDN by configuring the URL in next.config.js. Example: import confetti from 'https://cdn.skypack.dev/canvas-confetti'
URL imports with Next.js Image component example
You can use URL imports with the Next.js Image component: import Image from 'next/image'; import logo from 'https://example.com/assets/logo.png'; export default () => ( <div><Image src={logo} placeholder="blur" /></div> )
URL imports in CSS
You can use URLs directly in CSS background properties: .className { background: url('https://example.com/assets/hero.jpg'); }