turbopack-cli: add --persistent-caching flag for filesystem-backed cache#91657
turbopack-cli: add --persistent-caching flag for filesystem-backed cache#91657
Conversation
Merging this PR will not alter performance
Comparing Footnotes
|
Failing test suitesCommit: 7ab991a | About building and testing Next.js
Expand output● next-types-plugin › should have type for root page ● next-types-plugin › should have type for root layout ● next-types-plugin › should have type for nested page ● next-types-plugin › should have type for nested layout ● next-types-plugin › should have type for dynamic page ● next-types-plugin › should have type for dynamic layout |
Failing test suitesCommit: 110d762 | About building and testing Next.js
Expand output● dynamic-css-client-navigation react lazy nodejs › should not remove style when navigating from static imported component to react lazy at runtime nodejs
Expand output● Graceful Shutdown › production (standalone mode) › should not accept new requests during shutdown cleanup › should stop accepting new requests when shutting down
Expand output● use-node-streams env precedence › should respect explicit useNodeStreams=false even when env flag is true |
Stats from current PR✅ No significant changes detected📊 All Metrics📖 Metrics GlossaryDev Server Metrics:
Build Metrics:
Change Thresholds:
⚡ Dev Server
📦 Dev Server (Webpack) (Legacy)📦 Dev Server (Webpack)
⚡ Production Builds
📦 Production Builds (Webpack) (Legacy)📦 Production Builds (Webpack)
📦 Bundle SizesBundle Sizes⚡ TurbopackClient Main Bundles
Server Middleware
Build DetailsBuild Manifests
📦 WebpackClient Main Bundles
Polyfills
Pages
Server Edge SSR
Middleware
Build DetailsBuild Manifests
Build Cache
🔄 Shared (bundler-independent)Runtimes
📎 Tarball URL |
Adds `--persistent-caching` and `--cache-dir` CLI flags to both `turbopack dev` and `turbopack build`. When enabled, uses `turbo_backing_storage` with the git HEAD describe/dirty state as the cache version key, matching the same pattern used by next-napi-bindings. Co-Authored-By: Claude <[email protected]>
…nts fields The small_apps bench used a positional struct literal for CommonArguments which broke after adding persistent_caching and cache_dir fields. Add them with their false/None defaults. Co-Authored-By: Claude <[email protected]>
7ab991a to
51405d8
Compare
Co-Authored-By: Claude <[email protected]>
What?
Adds
--persistent-cachingand--cache-dirCLI flags toturbopack devandturbopack buildin the standaloneturbopack-clicrate.Why?
The standalone
turbopack-clibinary (used independently ofnext) had no way to opt into the filesystem-backed persistent cache that thenext-napi-bindingsintegration already supports. Without this, repeated builds always start cold — every incremental run re-computes the full task graph from scratch.How?
build.rs(new): A Cargo build script that usesvergen-gitclto emitVERGEN_GIT_DESCRIBEandVERGEN_GIT_DIRTYas compile-time env vars. These are used to key the cache by git version, matching the same approach asnext-napi-bindings. The build script embeds the dirty state at compile time rather than runtime to avoid a git subprocess on every startup.The dirty-state caching tradeoff (explained in the build script comment): there's a narrow edge case where the tree becomes newly dirty without triggering a Cargo rebuild, but in practice this is safe — if nothing in the crate changed, the binary is semantically equivalent to a clean build, so using the HEAD hash as the cache key is correct.
arguments.rs: Two new flags onCommonArguments(shared by bothdevandbuildsubcommands):--persistent-caching— opt-in flag to enable the filesystem cache--cache-dir <PATH>— override the cache directory (defaults to.turbopack/cachein the project root)dev/mod.rsandbuild/mod.rs:Backendtype alias changes fromTurboTasksBackend<NoopBackingStorage>toTurboTasksBackend<Either<TurboBackingStorage, NoopBackingStorage>>to unify the type without dynamic dispatch.--persistent-cachingis set: initializesTurboBackingStorageviaturbo_backing_storage(), selectsStorageMode::ReadWriteOnShutdownfor CI/short sessions andStorageMode::ReadWritefor interactive dev, and prints a warning if the cache was invalidated on startup.noop_backing_storage()— identical behavior to before.TURBO_ENGINE_READ_ONLYenv var to force read-only mode.