Turbopack: rename turbopackPersistentCachingForXXX to turbopackFileSystemCacheForXXX (#84632)

### What?

Improve naming of the feature: `Turbopack FileSystem Cache`

Author: sokra

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

@@ -7,8 +7,8 @@ const nextConfig = {
     ignoreBuildErrors: true,
   },
   experimental: {
-    turbopackPersistentCachingForDev: process.env.TURBO_CACHE === '1',
-    turbopackPersistentCachingForBuild: process.env.TURBO_CACHE === '1',
+    turbopackFileSystemCacheForDev: process.env.TURBO_CACHE === '1',
+    turbopackFileSystemCacheForBuild: process.env.TURBO_CACHE === '1',
   },
 }
 

crates/napi/build.rs

@@ -33,7 +33,7 @@ fn main() -> anyhow::Result<()> {
     let cargo = vergen_gitcl::CargoBuilder::default()
         .target_triple(true)
         .build()?;
-    // We use the git dirty state to disable persistent caching (persistent caching relies on a
+    // We use the git dirty state to disable filesystem cache (filesystem cache relies on a
     // commit hash to be safe). One tradeoff of this is that we must invalidate the rust build more
     // often.
     //
@@ -46,7 +46,7 @@ fn main() -> anyhow::Result<()> {
     //
     // However, in practice that shouldn't be much of an issue: If no other dependency of this
     // top-level crate has changed (which would've triggered our rebuild), then the resulting binary
-    // must be equivalent to a clean build anyways. Therefore, persistent caching using the HEAD
+    // must be equivalent to a clean build anyways. Therefore, filesystem cache using the HEAD
     // commit hash as a version is okay.
     let git = vergen_gitcl::GitclBuilder::default()
         .dirty(/* include_untracked */ true)

crates/napi/src/next_api/project.rs

@@ -238,7 +238,7 @@ pub struct NapiDefineEnv {
 
 #[napi(object)]
 pub struct NapiTurboEngineOptions {
-    /// Use the new backend with persistent caching enabled.
+    /// Use the new backend with filesystem cache enabled.
     pub persistent_caching: Option<bool>,
     /// An upper bound of memory that turbopack will attempt to stay under.
     pub memory_limit: Option<f64>,
@@ -602,10 +602,10 @@ pub async fn project_update(
         .await
 }
 
-/// Invalidates the persistent cache so that it will be deleted next time that a turbopack project
-/// is created with persistent caching enabled.
+/// Invalidates the filesystem cache so that it will be deleted next time that a turbopack project
+/// is created with filesystem cache enabled.
 #[napi]
-pub async fn project_invalidate_persistent_cache(
+pub async fn project_invalidate_file_system_cache(
     #[napi(ts_arg_type = "{ __napiType: \"Project\" }")] project: External<ProjectInstance>,
 ) -> napi::Result<()> {
     tokio::task::spawn_blocking(move || {
@@ -619,7 +619,7 @@ pub async fn project_invalidate_persistent_cache(
             .invalidate(invalidation_reasons::USER_REQUEST)
     })
     .await
-    .context("panicked while invalidating persistent cache")??;
+    .context("panicked while invalidating filesystem cache")??;
     Ok(())
 }
 

crates/napi/src/next_api/turbopack_ctx.rs

@@ -250,7 +250,7 @@ impl CompilationEvent for StartupCacheInvalidationEvent {
             _ => "", // ignore unknown reasons
         };
         format!(
-            "Turbopack's persistent cache has been deleted{reason_msg}. Builds or page loads may \
+            "Turbopack's filesystem cache has been deleted{reason_msg}. Builds or page loads may \
              be slower as a result."
         )
     }

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

@@ -0,0 +1,50 @@
+---
+title: Turbopack FileSystem Caching
+nav_title: turbopackFileSystemCache
+description: Learn how to enable FileSystem Caching for Turbopack builds
+version: canary
+---
+
+## Usage
+
+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.
+
+> **Warning:** FileSystem Cache is still under development and is not yet stable. Users adopting should expect some stability issues.
+
+> **Good to know**: Note that while `next dev` and `next build` can share cached data with each other, most cache entries are command-specific due to different configuration and environment variables.
+
+```ts filename="next.config.ts" switcher
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  experimental: {
+    // Enable filesystem caching for `next dev`
+    turbopackFileSystemCacheForDev: true,
+    // Enable filesystem caching for `next build`
+    turbopackFileSystemCacheForBuild: true,
+  },
+}
+
+export default nextConfig
+```
+
+```js filename="next.config.js" switcher
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    // Enable filesystem caching for `next dev`
+    turbopackFileSystemCacheForDev: true,
+    // Enable filesystem caching for `next build`
+    turbopackFileSystemCacheForBuild: true,
+  },
+}
+
+module.exports = nextConfig
+```
+
+## Version Changes
+
+| Version   | Changes                                     |
+| --------- | ------------------------------------------- |
+| `v16.0.0` | Separate flags for build and dev.           |
+| `v15.5.0` | Persistent caching released as experimental |

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

@@ -140,7 +140,7 @@ We are planning to offer an equivalent to the `innerGraph` optimization in Turbo
 
 ### Build Caching
 
-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).
+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.turbopackFileSystemCacheForDev`/`experimental.turbopackFileSystemCacheForBuild` flags](/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache).
 
 > **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.
 

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

@@ -6,7 +6,7 @@ title: No Cache Detected
 
 A Next.js build was triggered in a continuous integration environment, but no cache was detected.
 
-This results in slower builds and can hurt Next.js' persistent caching of client-side bundles across builds.
+This results in slower builds and can hurt Next.js' filesystem cache of client-side bundles across builds.
 
 ## Possible Ways to Fix It
 

errors/no-cache.mdx

@@ -320,19 +320,19 @@ export function getDefineEnv({
 
     // The devtools need to know whether or not to show an option to clear the
     // bundler cache. This option may be removed later once Turbopack's
-    // persistent cache feature is more stable.
+    // filesystem cache feature is more stable.
     //
     // This environment value is currently best-effort:
     // - It's possible to disable the webpack filesystem cache, but it's
     //   unlikely for a user to do that.
-    // - Rspack's persistent cache is unstable and requires a different
+    // - Rspack's filesystem cache is unstable and requires a different
     //   configuration than webpack to enable (which we don't do).
     //
     // In the worst case we'll show an option to clear the cache, but it'll be a
     // no-op that just restarts the development server.
     'process.env.__NEXT_BUNDLER_HAS_PERSISTENT_CACHE':
       !isTurbopack ||
-      (config.experimental.turbopackPersistentCachingForDev ?? false),
+      (config.experimental.turbopackFileSystemCacheForDev ?? false),
     'process.env.__NEXT_REACT_DEBUG_CHANNEL':
       config.experimental.reactDebugChannel ?? false,
   }

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

@@ -206,7 +206,7 @@ import {
 } from '../server/lib/router-utils/build-prefetch-segment-data-route'
 
 import { turbopackBuild } from './turbopack-build'
-import { isPersistentCachingEnabledForBuild } from '../shared/lib/turbopack/utils'
+import { isFileSystemCacheEnabledForBuild } from '../shared/lib/turbopack/utils'
 import { inlineStaticEnv } from '../lib/inline-static-env'
 import { populateStaticEnv } from '../lib/static-env'
 import { durationToString, hrtimeDurationToString } from './duration-to-string'
@@ -2728,8 +2728,8 @@ export default async function build(
           invocationCount: config.experimental.ppr ? 1 : 0,
         },
         {
-          featureName: 'turbopackPersistentCaching',
-          invocationCount: isPersistentCachingEnabledForBuild(config) ? 1 : 0,
+          featureName: 'turbopackFileSystemCache',
+          invocationCount: isFileSystemCacheEnabledForBuild(config) ? 1 : 0,
         },
       ]
       telemetry.record(