Skip to content

Commit 3d4d46f

Browse files
timneutkenstimneutkens
authored
Enable Turbopack build filesystem cache by default (#96493)
## Summary Enable `experimental.turbopackFileSystemCacheForBuild` by default in all environments, including generic CI. Explicitly setting the option to `false` remains the opt-out. Update the focused coverage and documentation to match. ## Verification - `IS_TURBOPACK_TEST=1 pnpm test-start-turbo test/e2e/filesystem-cache/build-cache-default.test.ts` - `pnpm prettier --with-node-modules --ignore-path .prettierignore --check packages/next/src/server/config-shared.ts test/e2e/filesystem-cache/build-cache-default.test.ts docs/01-app/03-api-reference/08-turbopack.mdx docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackFileSystemCache.mdx` - Not run: `pnpm --filter=next build` (the checkout has 11 pre-existing TypeScript errors in unrelated files) <!-- NEXT_JS_LLM -->
1 parent 9480f7f commit 3d4d46f

4 files changed

Lines changed: 22 additions & 42 deletions

File tree

‎docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackFileSystemCache.mdx‎

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,7 @@ description: Learn how to enable FileSystem Caching for Turbopack builds
88

99
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.
1010

11-
> **Good to know:** The FileSystem Cache is **enabled by default** for `next dev`. It is enabled by default when running `next build` locally or on Vercel, where the cache is likely to persist between builds. You can explicitly enable or disable it with the flags below.
12-
13-
> **For deployment providers:** Other providers can enable the build cache by default on their platform by setting `experimental.turbopackFileSystemCacheForBuild: true` from their adapter's [`modifyConfig`](/docs/app/api-reference/adapters/creating-an-adapter) hook. Do this when your infrastructure preserves the `.next/cache` directory between builds, and only when the user has not set an explicit value for the flag.
11+
> **Good to know:** The FileSystem Cache is **enabled by default** for `next dev` and `next build`. You can explicitly disable it with the flags below when your build environment does not preserve the `.next/cache` directory between builds.
1412
1513
```ts filename="next.config.ts" switcher
1614
import type { NextConfig } from 'next'
@@ -41,9 +39,9 @@ module.exports = nextConfig
4139

4240
## Version Changes
4341

44-
| Version | Changes |
45-
| --------- | ------------------------------------------------------------------------------------ |
46-
| `v16.3.0` | FileSystem caching is enabled by default for builds (depends on CI platform support) |
47-
| `v16.1.0` | FileSystem caching is enabled by default for development |
48-
| `v16.0.0` | Beta release with separate flags for build and dev |
49-
| `v15.5.0` | Persistent caching released as experimental on canary releases |
42+
| Version | Changes |
43+
| --------- | -------------------------------------------------------------- |
44+
| `v16.3.0` | FileSystem caching is enabled by default for builds |
45+
| `v16.1.0` | FileSystem caching is enabled by default for development |
46+
| `v16.0.0` | Beta release with separate flags for build and dev |
47+
| `v15.5.0` | Persistent caching released as experimental on canary releases |

‎docs/01-app/03-api-reference/08-turbopack.mdx‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -349,9 +349,7 @@ This can lead to subtle rendering differences when migrating from webpack to Tur
349349
Webpack supports [disk build caching](https://webpack.js.org/configuration/cache/#cache) to improve build performance. Turbopack provides a similar feature. Starting with Next 16, Turbopack's filesystem cache is controlled by the following experimental flags:
350350

351351
- [`experimental.turbopackFileSystemCacheForDev`](/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache) is enabled by default
352-
- [`experimental.turbopackFileSystemCacheForBuild`](/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache) is enabled by default for local builds and on Vercel, where the build cache is likely to persist.
353-
354-
Other deployment providers can enable the build cache by default on their platform by setting `experimental.turbopackFileSystemCacheForBuild: true` from their adapter's [`modifyConfig`](/docs/app/api-reference/adapters/creating-an-adapter) hook, when their infrastructure preserves the `.next/cache` directory between builds.
352+
- [`experimental.turbopackFileSystemCacheForBuild`](/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache) is enabled by default
355353

356354
> **Good to know:** For this reason, when comparing webpack and Turbopack performance, make sure to delete the `.next` folder between builds to see a fair cold build comparison or enable the turbopack filesystem cache feature to compare warm builds.
357355
@@ -422,9 +420,8 @@ Additionally, the following experimental options are available under `experiment
422420
| [`turbopackLocalPostcssConfig`](/docs/app/api-reference/config/next-config-js/turbopackLocalPostcssConfig) | Resolve `postcss.config.js` from the CSS file's directory first, then the project root. | `false` | `false` |
423421
| `turbopackWorkerAssetPrefix` | Custom asset prefix for Web Worker URLs (entrypoint + module chunks), overriding `assetPrefix`. Mirrors webpack's `output.workerPublicPath`. | `undefined` | `undefined` |
424422

425-
<sup>1</sup> Enabled by default for local builds and on CI platforms (including
426-
Vercel) where the build cache is likely to persist. Disabled by default on CI
427-
platforms that have not yet opted into the feature.
423+
<sup>1</sup> Enabled by default. Set the option to `false` when the build
424+
environment does not preserve the `.next/cache` directory between builds.
428425

429426
```js filename="next.config.js"
430427
module.exports = {

‎packages/next/src/server/config-shared.ts‎

Lines changed: 2 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ import { INFINITE_CACHE } from '../lib/constants'
1616
import type { FallbackRouteParam } from '../build/static-paths/types'
1717
import type { MemoryEvictionMode } from '../build/swc/types'
1818
import type { CacheLife } from './use-cache/cache-life'
19-
import { isCI } from './ci-info'
2019

2120
/**
2221
* The `cacheLife` profiles after config normalization. `config.ts` always
@@ -881,7 +880,7 @@ export interface ExperimentalConfig {
881880
/**
882881
* Enable filesystem cache for the turbopack build.
883882
*
884-
* Defaults to `true` in canary/preview builds, `false` in production.
883+
* Defaults to `true`.
885884
*/
886885
turbopackFileSystemCacheForBuild?: boolean
887886

@@ -2250,20 +2249,14 @@ export const defaultConfig = Object.freeze({
22502249
hideLogsAfterAbort: false,
22512250
mcpServer: true,
22522251
turbopackFileSystemCacheForDev: true,
2253-
turbopackFileSystemCacheForBuild: turbopackFileSystemCacheForBuildDefault(),
2252+
turbopackFileSystemCacheForBuild: true,
22542253
turbopackInferModuleSideEffects: true,
22552254
turbopackPluginRuntimeStrategy: 'childProcesses',
22562255
},
22572256
htmlLimitedBots: undefined,
22582257
bundlePagesRouterDependencies: false,
22592258
} satisfies NextConfig)
22602259

2261-
function turbopackFileSystemCacheForBuildDefault() {
2262-
// Disable in most CI environments, because we don't know if the cache will persist across builds.
2263-
// Providers: Override the default behavior using `modifyConfig` in your adapter.
2264-
return !isCI || Boolean(process.env.NOW_BUILDER)
2265-
}
2266-
22672260
export async function normalizeConfig(phase: string, config: any) {
22682261
if (typeof config === 'function') {
22692262
config = config(phase, { defaultConfig })

‎test/e2e/filesystem-cache/build-cache-default.test.ts‎

Lines changed: 10 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,13 @@ import { nextTestSetup, isNextStart } from 'e2e-utils'
22
import fs from 'fs/promises'
33
import path from 'path'
44

5-
// `experimental.turbopackFileSystemCacheForBuild` is enabled by default, except
6-
// in CI environments that haven't opted in (`isCI && !NOW_BUILDER`), where the
7-
// cache is unlikely to persist between builds. It can always be disabled
8-
// explicitly with `turbopackFileSystemCacheForBuild: false`.
5+
// `experimental.turbopackFileSystemCacheForBuild` is enabled by default in all
6+
// environments. It can be disabled explicitly with
7+
// `turbopackFileSystemCacheForBuild: false`.
98
//
10-
// This is a Turbopack + build (start) mode test. It runs `next build` with a
11-
// controlled environment (the default depends on ambient `isCI`/`NOW_BUILDER`,
12-
// and the test runner itself runs in CI) and checks whether anything is written
9+
// This is a Turbopack + build (start) mode test. It runs `next build` with
10+
// controlled local and CI environments and checks whether anything is written
1311
// to `.next/cache/turbopack`.
14-
//
15-
// `next/dist/compiled/ci-info` computes
16-
// isCI = !!(CI || CONTINUOUS_INTEGRATION || BUILD_NUMBER || RUN_ID || <vendor>)
17-
// so clearing those signals forces a non-CI environment, and setting `CI=1`
18-
// (with `NOW_BUILDER` unset) forces a CI environment that hasn't opted in.
1912
;(process.env.IS_TURBOPACK_TEST && isNextStart ? describe : describe.skip)(
2013
'filesystem-cache build default',
2114
() => {
@@ -29,8 +22,7 @@ import path from 'path'
2922
return
3023
}
3124

32-
// Simulate a non-CI (local) environment by clearing every CI signal that
33-
// `ci-info` looks at.
25+
// Simulate a non-CI (local) environment by clearing the common CI signals.
3426
const NON_CI_ENV = {
3527
CI: '',
3628
CONTINUOUS_INTEGRATION: '',
@@ -89,7 +81,7 @@ import path from 'path'
8981
await setConfig()
9082
})
9183

92-
it('writes the cache by default (no config, non-CI environment)', async () => {
84+
it('writes the cache by default (no config, local environment)', async () => {
9385
await cleanBuildOutput()
9486
await setConfig()
9587

@@ -109,17 +101,17 @@ import path from 'path'
109101
expect(await getCacheSize()).toBe(0)
110102
})
111103

112-
it('writes nothing by default in CI that has not opted in', async () => {
104+
it('writes the cache by default in CI', async () => {
113105
await cleanBuildOutput()
114106
await setConfig()
115107

116108
const { exitCode } = await next.build({
117-
// Force a CI environment that hasn't opted in: `isCI` true, `NOW_BUILDER` unset.
109+
// Force a generic CI environment.
118110
env: { ...NON_CI_ENV, CI: '1' },
119111
})
120112
expect(exitCode).toBe(0)
121113

122-
expect(await getCacheSize()).toBe(0)
114+
expect(await getCacheSize()).toBeGreaterThan(0)
123115
})
124116
}
125117
)

0 commit comments

Comments
 (0)