Skip to content

Commit 8586cdf

Browse files
authored
Turbopack: add separate turbopackPersistentCachingForBuild/ForDev flags (#84215)
### What? Move persistent caching for `next build` into a separate config option: `turbopackPersistentCachingForBuild`. And `next dev` to `turbopackPersistentCachingForDev`.
1 parent 08773fa commit 8586cdf

File tree

15 files changed

+68
-25
lines changed

15 files changed

+68
-25
lines changed

bench/heavy-npm-deps/next.config.mjs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ const nextConfig = {
77
ignoreBuildErrors: true,
88
},
99
experimental: {
10-
turbopackPersistentCaching: process.env.TURBO_CACHE === '1',
10+
turbopackPersistentCachingForDev: process.env.TURBO_CACHE === '1',
11+
turbopackPersistentCachingForBuild: process.env.TURBO_CACHE === '1',
1112
},
1213
}
1314

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

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,10 @@ import type { NextConfig } from 'next'
1818

1919
const nextConfig: NextConfig = {
2020
experimental: {
21-
turbopackPersistentCaching: true,
21+
// Enable persistent caching for `next dev`
22+
turbopackPersistentCachingForDev: true,
23+
// Enable persistent caching for `next build`
24+
turbopackPersistentCachingForBuild: true,
2225
},
2326
}
2427

@@ -29,7 +32,10 @@ export default nextConfig
2932
/** @type {import('next').NextConfig} */
3033
const nextConfig = {
3134
experimental: {
32-
turbopackPersistentCaching: true,
35+
// Enable persistent caching for `next dev`
36+
turbopackPersistentCachingForDev: true,
37+
// Enable persistent caching for `next build`
38+
turbopackPersistentCachingForBuild: true,
3339
},
3440
}
3541

@@ -40,4 +46,5 @@ module.exports = nextConfig
4046

4147
| Version | Changes |
4248
| --------- | ------------------------------------------- |
49+
| `v16.0.0` | Separate flags for build and dev. |
4350
| `v15.5.0` | Persistent caching released as experimental |

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,7 @@ We are planning to offer an equivalent to the `innerGraph` optimization in Turbo
140140

141141
### Build Caching
142142

143-
Webpack supports [disk build caching](https://webpack.js.org/configuration/cache/#cache) to speed up builds. We are planning to support an analogous feature in Turbopack but it is not ready yet. On the `next@canary` release you can experiment with our solution by enabling the [`experimental.turbopackPersistentCaching` flag](/docs/app/api-reference/config/next-config-js/turbopackPersistentCaching).
143+
Webpack supports [disk build caching](https://webpack.js.org/configuration/cache/#cache) to speed up builds. We are planning to support an analogous feature in Turbopack but it is not ready yet. On the `next@canary` release you can experiment with our solution by enabling the [`experimental.turbopackPersistentCachingForDev`/`experimental.turbopackPersistentCachingForBuild` flags](/docs/app/api-reference/config/next-config-js/turbopackPersistentCaching).
144144

145145
> **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 comparison.
146146

packages/next/src/build/define-env.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -331,7 +331,8 @@ export function getDefineEnv({
331331
// In the worst case we'll show an option to clear the cache, but it'll be a
332332
// no-op that just restarts the development server.
333333
'process.env.__NEXT_BUNDLER_HAS_PERSISTENT_CACHE':
334-
!isTurbopack || (config.experimental.turbopackPersistentCaching ?? false),
334+
!isTurbopack ||
335+
(config.experimental.turbopackPersistentCachingForDev ?? false),
335336
'process.env.__NEXT_REACT_DEBUG_CHANNEL':
336337
config.experimental.reactDebugChannel ?? false,
337338
}

packages/next/src/build/index.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -206,7 +206,7 @@ import {
206206
} from '../server/lib/router-utils/build-prefetch-segment-data-route'
207207

208208
import { turbopackBuild } from './turbopack-build'
209-
import { isPersistentCachingEnabled } from '../shared/lib/turbopack/utils'
209+
import { isPersistentCachingEnabledForBuild } from '../shared/lib/turbopack/utils'
210210
import { inlineStaticEnv } from '../lib/inline-static-env'
211211
import { populateStaticEnv } from '../lib/static-env'
212212
import { durationToString } from './duration-to-string'
@@ -2756,7 +2756,7 @@ export default async function build(
27562756
},
27572757
{
27582758
featureName: 'turbopackPersistentCaching',
2759-
invocationCount: isPersistentCachingEnabled(config) ? 1 : 0,
2759+
invocationCount: isPersistentCachingEnabledForBuild(config) ? 1 : 0,
27602760
},
27612761
]
27622762
telemetry.record(

packages/next/src/build/turbopack-build/impl.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import path from 'path'
22
import { validateTurboNextConfig } from '../../lib/turbopack-warning'
33
import {
44
formatIssue,
5-
isPersistentCachingEnabled,
5+
isPersistentCachingEnabledForBuild,
66
isRelevantWarning,
77
} from '../../shared/lib/turbopack/utils'
88
import { NextBuildContext } from '../build-context'
@@ -50,7 +50,7 @@ export async function turbopackBuild(): Promise<{
5050

5151
const supportedBrowsers = getSupportedBrowsers(dir, dev)
5252

53-
const persistentCaching = isPersistentCachingEnabled(config)
53+
const persistentCaching = isPersistentCachingEnabledForBuild(config)
5454
const rootPath = config.turbopack?.root || config.outputFileTracingRoot || dir
5555
const project = await bindings.turbo.createProject(
5656
{

packages/next/src/server/config-schema.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -436,7 +436,8 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
436436
webpackMemoryOptimizations: z.boolean().optional(),
437437
turbopackMemoryLimit: z.number().optional(),
438438
turbopackMinify: z.boolean().optional(),
439-
turbopackPersistentCaching: z.boolean().optional(),
439+
turbopackPersistentCachingForDev: z.boolean().optional(),
440+
turbopackPersistentCachingForBuild: z.boolean().optional(),
440441
turbopackSourceMaps: z.boolean().optional(),
441442
turbopackTreeShaking: z.boolean().optional(),
442443
turbopackRemoveUnusedExports: z.boolean().optional(),

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

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -423,9 +423,14 @@ export interface ExperimentalConfig {
423423
turbopackScopeHoisting?: boolean
424424

425425
/**
426-
* Enable persistent caching for the turbopack dev server and build.
426+
* Enable persistent caching for the turbopack dev server.
427427
*/
428-
turbopackPersistentCaching?: boolean
428+
turbopackPersistentCachingForDev?: boolean
429+
430+
/**
431+
* Enable persistent caching for the turbopack build.
432+
*/
433+
turbopackPersistentCachingForBuild?: boolean
429434

430435
/**
431436
* Enable source maps. Defaults to true.

packages/next/src/server/config.test.ts

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -133,17 +133,31 @@ describe('loadConfig', () => {
133133
)
134134
})
135135

136-
it('errors when using persistentCaching if not in canary', async () => {
136+
it('errors when using persistentCachingForDev if not in canary', async () => {
137137
await expect(
138138
loadConfig(PHASE_PRODUCTION_BUILD, __dirname, {
139139
customConfig: {
140140
experimental: {
141-
turbopackPersistentCaching: true,
141+
turbopackPersistentCachingForDev: true,
142142
},
143143
},
144144
})
145145
).rejects.toThrow(
146-
/The experimental feature "experimental.turbopackPersistentCaching" can only be enabled when using the latest canary version of Next.js./
146+
/The experimental feature "experimental.turbopackPersistentCachingForDev" can only be enabled when using the latest canary version of Next.js./
147+
)
148+
})
149+
150+
it('errors when using persistentCachingForBuild if not in canary', async () => {
151+
await expect(
152+
loadConfig(PHASE_PRODUCTION_BUILD, __dirname, {
153+
customConfig: {
154+
experimental: {
155+
turbopackPersistentCachingForBuild: true,
156+
},
157+
},
158+
})
159+
).rejects.toThrow(
160+
/The experimental feature "experimental.turbopackPersistentCachingForBuild" can only be enabled when using the latest canary version of Next.js./
147161
)
148162
})
149163
})

packages/next/src/server/config.ts

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -354,9 +354,13 @@ function assignDefaultsAndValidate(
354354
throw new CanaryOnlyError({ feature: 'experimental.ppr' })
355355
} else if (result.experimental?.cacheComponents) {
356356
throw new CanaryOnlyError({ feature: 'experimental.cacheComponents' })
357-
} else if (result.experimental?.turbopackPersistentCaching) {
357+
} else if (result.experimental?.turbopackPersistentCachingForDev) {
358358
throw new CanaryOnlyError({
359-
feature: 'experimental.turbopackPersistentCaching',
359+
feature: 'experimental.turbopackPersistentCachingForDev',
360+
})
361+
} else if (result.experimental?.turbopackPersistentCachingForBuild) {
362+
throw new CanaryOnlyError({
363+
feature: 'experimental.turbopackPersistentCachingForBuild',
360364
})
361365
}
362366
}

0 commit comments

Comments
 (0)