Skip to content

[turbopack] Enable turbopackFileSystemCacheForDev by default and release turbopackFileSystemCacheForBuild to stable builds #85975

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: graphite-base/85975
Choose a base branch
from
+6 −16
Draft

[turbopack] Enable turbopackFileSystemCacheForDev by default and release turbopackFileSystemCacheForBuild to stable builds #85975

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
51fd761
Release turbopackFileSystemCacheForBuild to stable builds
lukesandberg Nov 10, 2025
72bd18b
update documentation
lukesandberg Nov 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion ...1-app/03-api-reference/05-config/01-next-config-js/turbopackFileSystemCache.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ description: Learn how to enable FileSystem Caching for Turbopack builds

Turbopack FileSystem Cache enables Turbopack to reduce work across `next dev` or `next build` commands. When enabled, Turbopack will save and restore data to the `.next` folder between builds, which can greatly speed up subsequent builds and dev sessions.

> **Good to know:** The FileSystem Cache feature is Beta and is still under development. Users adopting should expect some stability issues. We recommend first adopting it for development.
> **Good to know:** The FileSystem Cache feature is considered stable for development and experimental for production builds

```ts filename="next.config.ts" switcher
import type { NextConfig } from 'next'
Expand Down Expand Up @@ -43,5 +43,6 @@ module.exports = nextConfig

| Version | Changes |
| --------- | -------------------------------------------------------------- |
| `v16.1.0` | FileSystem caching is enabled by default for development |
| `v16.0.0` | Beta release with separate flags for build and dev |
| `v15.5.0` | Persistent caching released as experimental on canary releases |
6 changes: 4 additions & 2 deletions packages/next/src/server/config-shared.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -416,12 +416,14 @@ export interface ExperimentalConfig {
/**
* Enable filesystem cache for the turbopack dev server.
*
* Defaults to `true` in canary releases.
* Defaults to `true`.
*/
turbopackFileSystemCacheForDev?: boolean

/**
* Enable filesystem cache for the turbopack build.
*
* Defaults to `false`.
*/
turbopackFileSystemCacheForBuild?: boolean

Expand Down Expand Up @@ -1534,7 +1536,7 @@ export const defaultConfig = Object.freeze({
proxyClientMaxBodySize: 10_485_760, // 10MB
hideLogsAfterAbort: false,
mcpServer: true,
turbopackFileSystemCacheForDev: !isStableBuild(),
turbopackFileSystemCacheForDev: true,
turbopackFileSystemCacheForBuild: false,
},
htmlLimitedBots: undefined,
Expand Down
13 changes: 0 additions & 13 deletions packages/next/src/server/config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,6 @@ import { dset } from '../shared/lib/dset'
import { normalizeZodErrors } from '../shared/lib/zod'
import { HTML_LIMITED_BOT_UA_RE_STRING } from '../shared/lib/router/utils/is-bot'
import { findDir } from '../lib/find-pages-dir'
import {
CanaryOnlyConfigError,
isStableBuild,
} from '../shared/lib/errors/canary-only-config-error'
import { interopDefault } from '../lib/interop-default'
import { djb2Hash } from '../shared/lib/hash'
import type { NextAdapter } from '../build/adapter/build-complete'
Expand Down Expand Up @@ -398,15 +394,6 @@ function assignDefaultsAndValidate(
)
}

if (isStableBuild()) {
Copy link
Contributor

@vercel vercel bot Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The removal of the canary-only check for turbopackFileSystemCacheForBuild will cause the existing test in config.test.ts (line 99-111) to fail, as the test expects this validation error to be thrown but the code no longer throws it.

View Details
📝 Patch Details 
diff --git a/packages/next/src/server/config.test.ts b/packages/next/src/server/config.test.ts
index d7d558925c..94de69ccfe 100644
--- a/packages/next/src/server/config.test.ts
+++ b/packages/next/src/server/config.test.ts
@@ -95,20 +95,6 @@ describe('loadConfig', () => {
         /`experimental\.ppr` has been merged into `cacheComponents`/
       )
     })
-
-    it('errors when using persistentCachingForBuild if not in canary', async () => {
-      await expect(
-        loadConfig(PHASE_PRODUCTION_BUILD, __dirname, {
-          customConfig: {
-            experimental: {
-              turbopackFileSystemCacheForBuild: true,
-            },
-          },
-        })
-      ).rejects.toThrow(
-        /The experimental feature "experimental.turbopackFileSystemCacheForBuild" can only be enabled when using the latest canary version of Next.js./
-      )
-    })
   })
 
   describe('with a canary version', () => {

Analysis

Test failure: outdated canary-only validation check for turbopackFileSystemCacheForBuild

What fails: Test errors when using persistentCachingForBuild if not in canary in packages/next/src/server/config.test.ts (lines 99-111) expects a validation error to be thrown when experimental.turbopackFileSystemCacheForBuild is used in non-canary builds, but the validation code was removed.

How to reproduce:

pnpm testonly -- packages/next/src/server/config.test.ts --testNamePattern="errors when using persistentCachingForBuild if not in canary"

Result: Test fails with error: Expected: toThrow but no error was thrown. The config loads successfully with turbopackFileSystemCacheForBuild: true in stable builds.

Expected behavior: Since commit 51fd761f4b ("Release turbopackFileSystemCacheForBuild to stable builds") intentionally removed the canary-only restriction from config.ts (lines 398-408 in the original code), the test should be removed or updated to verify the feature now works in stable builds.

Fix: Removed the outdated test as the feature is now available in stable builds. The test was checking for a validation that no longer exists by design. All remaining tests pass (1804 tests in total).

// Prevents usage of certain experimental features outside of canary
if (result.experimental.turbopackFileSystemCacheForBuild) {
throw new CanaryOnlyConfigError({
feature: 'experimental.turbopackFileSystemCacheForBuild',
})
}
}

if (result.experimental.ppr) {
throw new HardDeprecatedConfigError(
`\`experimental.ppr\` has been merged into \`cacheComponents\`. The Partial Prerendering feature is still available, but is now enabled via \`cacheComponents\`. Please update your ${configFileName} accordingly.`
Expand Down
Loading