From 878720f15686d188a157e86e30275522d288af58 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 13 Feb 2025 15:51:18 +0100
Subject: [PATCH 01/17] minor Webpack env vars refactor

---
 packages/docusaurus-faster/package.json |   2 +-
 packages/docusaurus/src/webpack/base.ts |  35 +++++---
 yarn.lock                               | 110 ++++++++++++------------
 3 files changed, 79 insertions(+), 68 deletions(-)

diff --git a/packages/docusaurus-faster/package.json b/packages/docusaurus-faster/package.json
index 7ab71c5fed4c..6f2870a5cc9e 100644
--- a/packages/docusaurus-faster/package.json
+++ b/packages/docusaurus-faster/package.json
@@ -19,7 +19,7 @@
   "license": "MIT",
   "dependencies": {
     "@docusaurus/types": "3.7.0",
-    "@rspack/core": "^1.2.2",
+    "@rspack/core": "^1.2.3",
     "@swc/core": "^1.7.39",
     "@swc/html": "^1.7.39",
     "browserslist": "^4.24.2",
diff --git a/packages/docusaurus/src/webpack/base.ts b/packages/docusaurus/src/webpack/base.ts
index 6a77aa0f03f7..206910eef9de 100644
--- a/packages/docusaurus/src/webpack/base.ts
+++ b/packages/docusaurus/src/webpack/base.ts
@@ -35,9 +35,19 @@ const LibrariesToTranspileRegex = new RegExp(
   LibrariesToTranspile.map((libName) => `(node_modules/${libName})`).join('|'),
 );
 
+// TODO later: centralize/validate all env variables in a single place
+const Env = {
+  isProd: process.env.NODE_ENV === 'production',
+
+  // Secret flags to disable features that may cause troubles
+  noReactAliases: !!process.env.DOCUSAURUS_NO_REACT_ALIASES,
+  noPersistentCache: !!process.env.DOCUSAURUS_NO_PERSISTENT_CACHE,
+  noRspackIncremental: !!process.env.DOCUSAURUS_NO_RSPACK_INCREMENTAL,
+};
+
 function getReactAliases(siteDir: string): Record<string, string> {
   // Escape hatch
-  if (process.env.DOCUSAURUS_NO_REACT_ALIASES) {
+  if (Env.noReactAliases) {
     return {};
   }
   const resolveSitePkg = (id: string) =>
@@ -87,13 +97,12 @@ export async function createBaseConfig({
     plugins,
   } = props;
   const totalPages = routesPaths.length;
-  const isProd = process.env.NODE_ENV === 'production';
-  const minimizeEnabled = minify && isProd;
+  const minimizeEnabled = minify && Env.isProd;
 
   const fileLoaderUtils = getFileLoaderUtils(isServer);
 
   const name = isServer ? 'server' : 'client';
-  const mode = isProd ? 'production' : 'development';
+  const mode = Env.isProd ? 'production' : 'development';
 
   const themeAliases = await loadThemeAliases({siteDir, plugins});
 
@@ -150,7 +159,7 @@ export async function createBaseConfig({
         // See https://github.com/web-infra-dev/rspress/pull/1631
         // See https://github.com/facebook/docusaurus/issues/10646
         // @ts-expect-error: Rspack-only, not available in Webpack typedefs
-        incremental: !isProd && !process.env.DISABLE_RSPACK_INCREMENTAL,
+        incremental: !isProd && !Env.noRspackIncremental,
       };
     }
     return undefined;
@@ -164,8 +173,10 @@ export async function createBaseConfig({
     output: {
       pathinfo: false,
       path: outDir,
-      filename: isProd ? 'assets/js/[name].[contenthash:8].js' : '[name].js',
-      chunkFilename: isProd
+      filename: Env.isProd
+        ? 'assets/js/[name].[contenthash:8].js'
+        : '[name].js',
+      chunkFilename: Env.isProd
         ? 'assets/js/[name].[contenthash:8].js'
         : '[name].js',
       publicPath:
@@ -176,7 +187,7 @@ export async function createBaseConfig({
     performance: {
       hints: false,
     },
-    devtool: isProd ? undefined : 'eval-cheap-module-source-map',
+    devtool: Env.isProd ? undefined : 'eval-cheap-module-source-map',
     resolve: {
       extensions: ['.wasm', '.mjs', '.js', '.jsx', '.ts', '.tsx', '.json'],
       symlinks: true, // See https://github.com/facebook/docusaurus/issues/3272
@@ -270,7 +281,7 @@ export async function createBaseConfig({
           exclude: CSS_MODULE_REGEX,
           use: configureWebpackUtils.getStyleLoaders(isServer, {
             importLoaders: 1,
-            sourceMap: !isProd,
+            sourceMap: !Env.isProd,
           }),
         },
         // Adds support for CSS Modules (https://github.com/css-modules/css-modules)
@@ -285,17 +296,17 @@ export async function createBaseConfig({
               exportOnlyLocals: isServer,
             },
             importLoaders: 1,
-            sourceMap: !isProd,
+            sourceMap: !Env.isProd,
           }),
         },
       ],
     },
     plugins: [
       new CSSExtractPlugin({
-        filename: isProd
+        filename: Env.isProd
           ? 'assets/css/[name].[contenthash:8].css'
           : '[name].css',
-        chunkFilename: isProd
+        chunkFilename: Env.isProd
           ? 'assets/css/[name].[contenthash:8].css'
           : '[name].css',
         // Remove css order warnings if css imports are not sorted
diff --git a/yarn.lock b/yarn.lock
index c4721c4388d4..c4372e3502d8 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3216,73 +3216,73 @@
     fs-extra "^11.1.1"
     lodash "^4.17.21"
 
-"@rspack/binding-darwin-arm64@1.2.2":
-  version "1.2.2"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-darwin-arm64/-/binding-darwin-arm64-1.2.2.tgz#e2444ef46b3ee689a6021ae757bb55a0dbe7b491"
-  integrity sha512-h23F8zEkXWhwMeScm0ZnN78Zh7hCDalxIWsm7bBS0eKadnlegUDwwCF8WE+8NjWr7bRzv0p3QBWlS5ufkcL4eA==
+"@rspack/binding-darwin-arm64@1.2.3":
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-darwin-arm64/-/binding-darwin-arm64-1.2.3.tgz#dc5d8eaff24107438182786f2e44cae5ee8a5a32"
+  integrity sha512-xuwYzhPgNCr4BtKXCU3xe4249TFsXAZglIlbxv8Qs3PeIarrZMRddcqH2zUXi+nJavNw3yN12sCYEzk1f+O4FQ==
 
-"@rspack/binding-darwin-x64@1.2.2":
-  version "1.2.2"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-darwin-x64/-/binding-darwin-x64-1.2.2.tgz#5a4b827692d3063a5d30577ba41f2d97ab452492"
-  integrity sha512-vG5s7FkEvwrGLfksyDRHwKAHUkhZt1zHZZXJQn4gZKjTBonje8ezdc7IFlDiWpC4S+oBYp73nDWkUzkGRbSdcQ==
+"@rspack/binding-darwin-x64@1.2.3":
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-darwin-x64/-/binding-darwin-x64-1.2.3.tgz#5f77c8be2ae238ce8f8f5e18dbb73c399baa4deb"
+  integrity sha512-afiIN8elcrO2EtO27UN0qyZqu5FXGUdclud56DrhvEfnWS3GGxJEdjA8XUYVXkfCYakdXHucIJKlkkgaAjEvHg==
 
-"@rspack/binding-linux-arm64-gnu@1.2.2":
-  version "1.2.2"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.2.2.tgz#9c07f56fcac8ddc12bb818868fd5194c80d11fb5"
-  integrity sha512-VykY/kiYOzO8E1nYzfJ9+gQEHxb5B6lt5wa8M6xFi5B6jEGU+OsaGskmAZB9/GFImeFDHxDPvhUalI4R9p8O2Q==
+"@rspack/binding-linux-arm64-gnu@1.2.3":
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.2.3.tgz#91935de2c9b885f051675ffe4fc7cd24c3c0c8c0"
+  integrity sha512-K2u/fPUmKujlKSWL3q2zaUu8/6ZK/bOGKcqJSib8jdanQQ/GFKwKtPAFOOa/vvqbzhDocqKOobFR10FhgJqCHg==
 
-"@rspack/binding-linux-arm64-musl@1.2.2":
-  version "1.2.2"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.2.2.tgz#e3aff4cd36de780f95ded65264363b444f7f3c4e"
-  integrity sha512-Z5vAC4wGfXi8XXZ6hs8Q06TYjr3zHf819HB4DI5i4C1eQTeKdZSyoFD0NHFG23bP4NWJffp8KhmoObcy9jBT5Q==
+"@rspack/binding-linux-arm64-musl@1.2.3":
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.2.3.tgz#88c439c0aa739e29643485ae9a1b86a8a1b1e787"
+  integrity sha512-mgovdzGb6cH9hQsjTyzDbfZWCPhTcoHcLro1P7UbiqcLPMDJp/k3Io9xV2/EJhaDA1aynIdq7XfY0fuk4+6Irw==
 
-"@rspack/binding-linux-x64-gnu@1.2.2":
-  version "1.2.2"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.2.2.tgz#5af03e8b21c4afecddd92d52f0994a7e4785aabd"
-  integrity sha512-o3pDaL+cH5EeRbDE9gZcdZpBgp5iXvYZBBhe8vZQllYgI4zN5MJEuleV7WplG3UwTXlgZg3Kht4RORSOPn96vg==
+"@rspack/binding-linux-x64-gnu@1.2.3":
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.2.3.tgz#083542adc8903735d1265e40c82c95046692921d"
+  integrity sha512-542lwJzB1RMGuVdBdA3cOWTlmL9okpOppHUBWcNCjmJM+9zTI+0jwjVe8HaqOqtuR8XzNsoCwT9QonU/GLcuhg==
 
-"@rspack/binding-linux-x64-musl@1.2.2":
-  version "1.2.2"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-x64-musl/-/binding-linux-x64-musl-1.2.2.tgz#e5be9d4d6d7e5369fa0708c3bc6281a8c52525ad"
-  integrity sha512-RE3e0xe4DdchHssttKzryDwjLkbrNk/4H59TkkWeGYJcLw41tmcOZVFQUOwKLUvXWVyif/vjvV/w1SMlqB4wQg==
+"@rspack/binding-linux-x64-musl@1.2.3":
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-x64-musl/-/binding-linux-x64-musl-1.2.3.tgz#bc2f1a857fdc613db3f113fb9088e9b73cb88dcc"
+  integrity sha512-dJromiREDcTWqzfCOI5y1IVoYmUnCv7vCp63AEq0+13fJJdk7+pcNN3VV2jOKpk9VECSvjg1c01wl+UzXAXFMw==
 
-"@rspack/binding-win32-arm64-msvc@1.2.2":
-  version "1.2.2"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.2.2.tgz#4b1e98a304f1ea10fefb1de2de8abc460a0a15a7"
-  integrity sha512-R+PKBYn6uzTaDdVqTHvjqiJPBr5ZHg1wg5UmFDLNH9OklzVFyQh1JInSdJRb7lzfzTRz6bEkkwUFBPQK/CGScw==
+"@rspack/binding-win32-arm64-msvc@1.2.3":
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.2.3.tgz#fdca01d1ad1be84055f48b0d336a7ec651f97bc4"
+  integrity sha512-S8ZKddMMQDGy8jx/R0i2m1XrmfY2CpI+t6lIEpsuZuKUR4MbOGKN2DuL4MDnT3m8JaYvC8ihsvQjBXQCy3SNxQ==
 
-"@rspack/binding-win32-ia32-msvc@1.2.2":
-  version "1.2.2"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-1.2.2.tgz#3eff46acf9b1e11b33846edf0f7f916e8aeeb5e6"
-  integrity sha512-dBqz3sRAGZ2f31FgzKLDvIRfq2haRP3X3XVCT0PsiMcvt7QJng+26aYYMy2THatd/nM8IwExYeitHWeiMBoruw==
+"@rspack/binding-win32-ia32-msvc@1.2.3":
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-1.2.3.tgz#08739da8427b251e385e800e4d4f9a5d77a58aa7"
+  integrity sha512-74lqSMKQJcJcgfFaxm+G9YVJSl2KK9/v4fRoMsWApztNy2qNgee+UguNBCOU6JLa3rVSj8Z5OVVDtJkGFrSvVg==
 
-"@rspack/binding-win32-x64-msvc@1.2.2":
-  version "1.2.2"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.2.2.tgz#6f4bf6a590ffbbda64316ef1dc0378c0c3d93f2e"
-  integrity sha512-eeAvaN831KG553cMSHkVldyk6YQn4ujgRHov6r1wtREq7CD3/ka9LMkJUepCN85K7XtwYT0N4KpFIQyf5GTGoA==
+"@rspack/binding-win32-x64-msvc@1.2.3":
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.2.3.tgz#a4c445adce3b7a7d09639278b1483b2e6b4550c7"
+  integrity sha512-fcU532PgFdd5Bil8jwQW0Dcb/80oM6V0qSstGIxZ4M77t4t8e/PcukXfORTL71FfNQ64Rd4Dp6XRl1NHNJVxeg==
 
-"@rspack/binding@1.2.2":
-  version "1.2.2"
-  resolved "https://registry.yarnpkg.com/@rspack/binding/-/binding-1.2.2.tgz#0be057d1668cfc753bfbf039704fb0eb1c69a953"
-  integrity sha512-GCZwpGFYlLTdJ2soPLwjw9z4LSZ+GdpbHNfBt3Cm/f/bAF8n6mZc7dHUqN893RFh7MPU17HNEL3fMw7XR+6pHg==
+"@rspack/binding@1.2.3":
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/@rspack/binding/-/binding-1.2.3.tgz#a17d0ffd5bf653f903e34a673e5b649e4eb9bfd6"
+  integrity sha512-enpOXZPQOJO800wdWcR7H5Dx5UZfwkaT0D0xsHD53WbpI09Z2KJbLX7I/i1FLLy3K1KQTB+2FIHLVdRikasXZA==
   optionalDependencies:
-    "@rspack/binding-darwin-arm64" "1.2.2"
-    "@rspack/binding-darwin-x64" "1.2.2"
-    "@rspack/binding-linux-arm64-gnu" "1.2.2"
-    "@rspack/binding-linux-arm64-musl" "1.2.2"
-    "@rspack/binding-linux-x64-gnu" "1.2.2"
-    "@rspack/binding-linux-x64-musl" "1.2.2"
-    "@rspack/binding-win32-arm64-msvc" "1.2.2"
-    "@rspack/binding-win32-ia32-msvc" "1.2.2"
-    "@rspack/binding-win32-x64-msvc" "1.2.2"
-
-"@rspack/core@^1.2.2":
-  version "1.2.2"
-  resolved "https://registry.yarnpkg.com/@rspack/core/-/core-1.2.2.tgz#c91b7d36aa080ca99459826ad2db0e665215da2c"
-  integrity sha512-EeHAmY65Uj62hSbUKesbrcWGE7jfUI887RD03G++Gj8jS4WPHEu1TFODXNOXg6pa7zyIvs2BK0Bm16Kwz8AEaQ==
+    "@rspack/binding-darwin-arm64" "1.2.3"
+    "@rspack/binding-darwin-x64" "1.2.3"
+    "@rspack/binding-linux-arm64-gnu" "1.2.3"
+    "@rspack/binding-linux-arm64-musl" "1.2.3"
+    "@rspack/binding-linux-x64-gnu" "1.2.3"
+    "@rspack/binding-linux-x64-musl" "1.2.3"
+    "@rspack/binding-win32-arm64-msvc" "1.2.3"
+    "@rspack/binding-win32-ia32-msvc" "1.2.3"
+    "@rspack/binding-win32-x64-msvc" "1.2.3"
+
+"@rspack/core@^1.2.3":
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/@rspack/core/-/core-1.2.3.tgz#72e76f0dc9a255759c4bcf88d40b2ff8e6a14985"
+  integrity sha512-BFgdUYf05/hjjY9Nlwq8DpWaRJN5w2kTl8ZJi20SRL60oAx+ZD2ABT+fsPhBiFSmfTZDdvGGIq5e3vfRzoIuqg==
   dependencies:
     "@module-federation/runtime-tools" "0.8.4"
-    "@rspack/binding" "1.2.2"
+    "@rspack/binding" "1.2.3"
     "@rspack/lite-tapable" "1.0.1"
     caniuse-lite "^1.0.30001616"
 

From 1a2aac37175a468b686a7e4083792ccd3c1e2c0b Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 13 Feb 2025 16:11:11 +0100
Subject: [PATCH 02/17] Add Rspack persistent caching

---
 packages/docusaurus/src/webpack/base.ts | 58 +++++++++++++++++--------
 1 file changed, 41 insertions(+), 17 deletions(-)

diff --git a/packages/docusaurus/src/webpack/base.ts b/packages/docusaurus/src/webpack/base.ts
index 206910eef9de..66f8d1373da1 100644
--- a/packages/docusaurus/src/webpack/base.ts
+++ b/packages/docusaurus/src/webpack/base.ts
@@ -112,19 +112,37 @@ export async function createBaseConfig({
     currentBundler: props.currentBundler,
   });
 
+  // Can we share the same cache across locales?
+  // Exploring that question at https://github.com/webpack/webpack/issues/13034
+  function getCacheName() {
+    return `${name}-${mode}-${props.i18n.currentLocale}`;
+  }
+
+  function getCacheBuildDependencies(): string[] {
+    return [
+      __filename,
+      path.join(__dirname, isServer ? 'server.js' : 'client.js'),
+      // Docusaurus config changes can affect MDX/JSX compilation, so we'd
+      // rather evict the cache.
+      // See https://github.com/questdb/questdb.io/issues/493
+      siteConfigPath,
+    ];
+  }
+
   function getCache(): Configuration['cache'] {
     if (props.currentBundler.name === 'rspack') {
-      // TODO Rspack only supports memory cache (as of Sept 2024)
-      // TODO re-enable file persistent cache one Rspack supports it
-      //  See also https://rspack.dev/config/cache#cache
-      return undefined;
+      if (Env.noPersistentCache) {
+        // Use default: memory cache in dev, nothing in prod
+        // See https://rspack.dev/config/cache#cache
+        return undefined;
+      }
+      // Use cache: true + experiments.cache.type: "persistent"
+      // See https://rspack.dev/config/experiments#persistent-cache
+      return true;
     }
     return {
       type: 'filesystem',
-      // Can we share the same cache across locales?
-      // Exploring that question at https://github.com/webpack/webpack/issues/13034
-      // name: `${name}-${mode}`,
-      name: `${name}-${mode}-${props.i18n.currentLocale}`,
+      name: getCacheName(),
       // When version string changes, cache is evicted
       version: [
         siteMetadata.docusaurusVersion,
@@ -136,20 +154,24 @@ export async function createBaseConfig({
       // When one of those modules/dependencies change (including transitive
       // deps), cache is invalidated
       buildDependencies: {
-        config: [
-          __filename,
-          path.join(__dirname, isServer ? 'server.js' : 'client.js'),
-          // Docusaurus config changes can affect MDX/JSX compilation, so we'd
-          // rather evict the cache.
-          // See https://github.com/questdb/questdb.io/issues/493
-          siteConfigPath,
-        ],
+        config: getCacheBuildDependencies(),
       },
     };
   }
 
   function getExperiments(): Configuration['experiments'] {
     if (props.currentBundler.name === 'rspack') {
+      const PersistentCacheAttributes = Env.noPersistentCache
+        ? {}
+        : {
+            cache: {
+              type: 'persistent',
+              version: getCacheName(),
+              buildDependencies: getCacheBuildDependencies(),
+            },
+          };
+
+      // TODO find a way to type this
       return {
         // This is mostly useful in dev
         // See https://rspack.dev/config/experiments#experimentsincremental
@@ -159,7 +181,9 @@ export async function createBaseConfig({
         // See https://github.com/web-infra-dev/rspress/pull/1631
         // See https://github.com/facebook/docusaurus/issues/10646
         // @ts-expect-error: Rspack-only, not available in Webpack typedefs
-        incremental: !isProd && !Env.noRspackIncremental,
+        incremental: !Env.isProd && !Env.noRspackIncremental,
+
+        ...PersistentCacheAttributes,
       };
     }
     return undefined;

From 7a9905ebd8ba91afe9225ab5adb5f1e3d386d7ad Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 13 Feb 2025 16:12:07 +0100
Subject: [PATCH 03/17] minor clear CLI label tweak

---
 packages/docusaurus/src/commands/clear.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docusaurus/src/commands/clear.ts b/packages/docusaurus/src/commands/clear.ts
index 1b8b7169c66a..5f46b548f012 100644
--- a/packages/docusaurus/src/commands/clear.ts
+++ b/packages/docusaurus/src/commands/clear.ts
@@ -40,7 +40,7 @@ export async function clear(siteDirParam: string = '.'): Promise<void> {
   // In Yarn PnP, cache is stored in `.yarn/.cache` because n_m doesn't exist
   const cacheFolders = ['node_modules', '.yarn'].map((p) => ({
     path: path.join(siteDir, p, '.cache'),
-    description: 'Webpack persistent cache folder',
+    description: 'Bundler persistent cache folder',
   }));
   await Promise.all(
     [generatedFolder, buildFolder, ...cacheFolders].map(removePath),

From 0e6f5316d5ab815aaff639adbade1116d57aead9 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 13 Feb 2025 16:14:49 +0100
Subject: [PATCH 04/17] docusaurus clear => use relative path output

---
 packages/docusaurus/src/commands/clear.ts | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/packages/docusaurus/src/commands/clear.ts b/packages/docusaurus/src/commands/clear.ts
index 5f46b548f012..0be7f40700ec 100644
--- a/packages/docusaurus/src/commands/clear.ts
+++ b/packages/docusaurus/src/commands/clear.ts
@@ -19,7 +19,10 @@ async function removePath(entry: {path: string; description: string}) {
   }
   try {
     await fs.remove(entry.path);
-    logger.success`Removed the ${entry.description} at path=${entry.path}.`;
+    logger.success`Removed the ${entry.description} at path=${path.relative(
+      process.cwd(),
+      entry.path,
+    )}.`;
   } catch (err) {
     logger.error`Could not remove the ${entry.description} at path=${entry.path}.`;
     logger.error(err);
@@ -40,7 +43,7 @@ export async function clear(siteDirParam: string = '.'): Promise<void> {
   // In Yarn PnP, cache is stored in `.yarn/.cache` because n_m doesn't exist
   const cacheFolders = ['node_modules', '.yarn'].map((p) => ({
     path: path.join(siteDir, p, '.cache'),
-    description: 'Bundler persistent cache folder',
+    description: 'bundler persistent cache folder',
   }));
   await Promise.all(
     [generatedFolder, buildFolder, ...cacheFolders].map(removePath),

From ae78a5fe803e0b6f187c11b290cd2b5972466dd2 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 13 Feb 2025 16:29:34 +0100
Subject: [PATCH 05/17] add Docusaurus version to cache name

---
 packages/docusaurus/src/webpack/base.ts | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/docusaurus/src/webpack/base.ts b/packages/docusaurus/src/webpack/base.ts
index 66f8d1373da1..0eada36be2ed 100644
--- a/packages/docusaurus/src/webpack/base.ts
+++ b/packages/docusaurus/src/webpack/base.ts
@@ -14,7 +14,11 @@ import {
   createJsLoaderFactory,
 } from '@docusaurus/bundler';
 
-import {md5Hash, getFileLoaderUtils} from '@docusaurus/utils';
+import {
+  md5Hash,
+  getFileLoaderUtils,
+  DOCUSAURUS_VERSION,
+} from '@docusaurus/utils';
 import {loadThemeAliases, loadDocusaurusAliases} from './aliases';
 import type {Configuration} from 'webpack';
 import type {
@@ -115,7 +119,7 @@ export async function createBaseConfig({
   // Can we share the same cache across locales?
   // Exploring that question at https://github.com/webpack/webpack/issues/13034
   function getCacheName() {
-    return `${name}-${mode}-${props.i18n.currentLocale}`;
+    return `${name}-${mode}-${props.i18n.currentLocale}-${DOCUSAURUS_VERSION}`;
   }
 
   function getCacheBuildDependencies(): string[] {

From 377a7e4f965e77b09647abd742eac6f6adeabe28 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 13 Feb 2025 16:30:00 +0100
Subject: [PATCH 06/17] Add clearer Docusaurus SSG renderer load error message

---
 packages/docusaurus/src/ssg/ssgRenderer.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docusaurus/src/ssg/ssgRenderer.ts b/packages/docusaurus/src/ssg/ssgRenderer.ts
index 91dcc5f4e660..3e0c2cf25336 100644
--- a/packages/docusaurus/src/ssg/ssgRenderer.ts
+++ b/packages/docusaurus/src/ssg/ssgRenderer.ts
@@ -83,7 +83,7 @@ async function loadAppRenderer({
 
   if (!serverEntry?.default || typeof serverEntry.default !== 'function') {
     throw new Error(
-      `Server bundle export from "${filename}" must be a function that renders the Docusaurus React app.`,
+      `Docusaurus Bug: server bundle export from "${filename}" must be a function that renders the Docusaurus React app, not ${typeof serverEntry?.default}`,
     );
   }
 

From 3bbd962311a03f43c38ced1dc4751ae6e5d8cf7c Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Fri, 14 Feb 2025 11:29:35 +0100
Subject: [PATCH 07/17] fix for cache name/version

---
 packages/docusaurus/src/webpack/base.ts | 34 ++++++++++++-------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/packages/docusaurus/src/webpack/base.ts b/packages/docusaurus/src/webpack/base.ts
index 0eada36be2ed..6e1bfffd0d4b 100644
--- a/packages/docusaurus/src/webpack/base.ts
+++ b/packages/docusaurus/src/webpack/base.ts
@@ -14,11 +14,7 @@ import {
   createJsLoaderFactory,
 } from '@docusaurus/bundler';
 
-import {
-  md5Hash,
-  getFileLoaderUtils,
-  DOCUSAURUS_VERSION,
-} from '@docusaurus/utils';
+import {md5Hash, getFileLoaderUtils} from '@docusaurus/utils';
 import {loadThemeAliases, loadDocusaurusAliases} from './aliases';
 import type {Configuration} from 'webpack';
 import type {
@@ -119,9 +115,19 @@ export async function createBaseConfig({
   // Can we share the same cache across locales?
   // Exploring that question at https://github.com/webpack/webpack/issues/13034
   function getCacheName() {
-    return `${name}-${mode}-${props.i18n.currentLocale}-${DOCUSAURUS_VERSION}`;
+    return `${name}-${mode}-${props.i18n.currentLocale}`;
+  }
+
+  // When the version string changes, the cache is evicted
+  function getCacheVersion() {
+    // Because Webpack does not evict the cache on alias/swizzle changes,
+    // See https://github.com/webpack/webpack/issues/13627
+    const themeAliasesHash = md5Hash(JSON.stringify(themeAliases));
+    return `${siteMetadata.docusaurusVersion}-${themeAliasesHash}`;
   }
 
+  // When one of those modules/dependencies change (including transitive
+  // deps), cache is invalidated
   function getCacheBuildDependencies(): string[] {
     return [
       __filename,
@@ -147,16 +153,7 @@ export async function createBaseConfig({
     return {
       type: 'filesystem',
       name: getCacheName(),
-      // When version string changes, cache is evicted
-      version: [
-        siteMetadata.docusaurusVersion,
-        // Webpack does not evict the cache correctly on alias/swizzle change,
-        // so we force eviction.
-        // See https://github.com/webpack/webpack/issues/13627
-        md5Hash(JSON.stringify(themeAliases)),
-      ].join('-'),
-      // When one of those modules/dependencies change (including transitive
-      // deps), cache is invalidated
+      version: getCacheVersion(),
       buildDependencies: {
         config: getCacheBuildDependencies(),
       },
@@ -170,7 +167,10 @@ export async function createBaseConfig({
         : {
             cache: {
               type: 'persistent',
-              version: getCacheName(),
+              // Rspack doesn't have "cache.name" like Webpack
+              // This is not ideal but work around is to merge name/version
+              // See https://github.com/facebook/docusaurus/pull/10931#discussion_r1955908019
+              version: `${getCacheName()}-${getCacheVersion()}`,
               buildDependencies: getCacheBuildDependencies(),
             },
           };

From b614cf6a95dc8c539817cebd646acfa5ad818e88 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Fri, 14 Feb 2025 11:38:05 +0100
Subject: [PATCH 08/17] update comment

---
 packages/docusaurus/src/webpack/base.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docusaurus/src/webpack/base.ts b/packages/docusaurus/src/webpack/base.ts
index 6e1bfffd0d4b..ebe4ffe1ae7e 100644
--- a/packages/docusaurus/src/webpack/base.ts
+++ b/packages/docusaurus/src/webpack/base.ts
@@ -169,7 +169,7 @@ export async function createBaseConfig({
               type: 'persistent',
               // Rspack doesn't have "cache.name" like Webpack
               // This is not ideal but work around is to merge name/version
-              // See https://github.com/facebook/docusaurus/pull/10931#discussion_r1955908019
+              // See https://github.com/web-infra-dev/rspack/pull/8920#issuecomment-2658938695
               version: `${getCacheName()}-${getCacheVersion()}`,
               buildDependencies: getCacheBuildDependencies(),
             },

From 2065d196bff5e40e159daad3a73238beb01a3eb9 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Fri, 14 Feb 2025 11:40:32 +0100
Subject: [PATCH 09/17] CI: increase e2e node heap memory size after enabling
 Rspack persistent caching

---
 .github/workflows/tests-e2e.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/tests-e2e.yml b/.github/workflows/tests-e2e.yml
index de30904ef072..7428d65a8404 100644
--- a/.github/workflows/tests-e2e.yml
+++ b/.github/workflows/tests-e2e.yml
@@ -68,7 +68,7 @@ jobs:
         env:
           # Our website should build even with limited memory
           # See https://github.com/facebook/docusaurus/pull/10590
-          NODE_OPTIONS: '--max-old-space-size=250'
+          NODE_OPTIONS: '--max-old-space-size=300'
           DOCUSAURUS_PERF_LOGGER: 'true'
         working-directory: ../test-website
 
@@ -181,7 +181,7 @@ jobs:
         env:
           # Our website should build even with limited memory
           # See https://github.com/facebook/docusaurus/pull/10590
-          NODE_OPTIONS: '--max-old-space-size=250'
+          NODE_OPTIONS: '--max-old-space-size=300'
           DOCUSAURUS_PERF_LOGGER: 'true'
         working-directory: ../test-website
 
@@ -223,6 +223,6 @@ jobs:
         env:
           # Our website should build even with limited memory
           # See https://github.com/facebook/docusaurus/pull/10590
-          NODE_OPTIONS: '--max-old-space-size=250'
+          NODE_OPTIONS: '--max-old-space-size=300'
           DOCUSAURUS_PERF_LOGGER: 'true'
         working-directory: ../test-website

From fc3657dad88ed8723263db0d58fe9b50263ea96d Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Fri, 14 Feb 2025 18:45:36 +0100
Subject: [PATCH 10/17] revert Env change

---
 packages/docusaurus/src/webpack/base.ts | 48 ++++++++++---------------
 1 file changed, 19 insertions(+), 29 deletions(-)

diff --git a/packages/docusaurus/src/webpack/base.ts b/packages/docusaurus/src/webpack/base.ts
index ebe4ffe1ae7e..3f2b681ff792 100644
--- a/packages/docusaurus/src/webpack/base.ts
+++ b/packages/docusaurus/src/webpack/base.ts
@@ -35,19 +35,9 @@ const LibrariesToTranspileRegex = new RegExp(
   LibrariesToTranspile.map((libName) => `(node_modules/${libName})`).join('|'),
 );
 
-// TODO later: centralize/validate all env variables in a single place
-const Env = {
-  isProd: process.env.NODE_ENV === 'production',
-
-  // Secret flags to disable features that may cause troubles
-  noReactAliases: !!process.env.DOCUSAURUS_NO_REACT_ALIASES,
-  noPersistentCache: !!process.env.DOCUSAURUS_NO_PERSISTENT_CACHE,
-  noRspackIncremental: !!process.env.DOCUSAURUS_NO_RSPACK_INCREMENTAL,
-};
-
 function getReactAliases(siteDir: string): Record<string, string> {
   // Escape hatch
-  if (Env.noReactAliases) {
+  if (process.env.DOCUSAURUS_NO_REACT_ALIASES) {
     return {};
   }
   const resolveSitePkg = (id: string) =>
@@ -97,12 +87,13 @@ export async function createBaseConfig({
     plugins,
   } = props;
   const totalPages = routesPaths.length;
-  const minimizeEnabled = minify && Env.isProd;
+  const isProd = process.env.NODE_ENV === 'production';
+  const minimizeEnabled = minify && isProd;
 
   const fileLoaderUtils = getFileLoaderUtils(isServer);
 
   const name = isServer ? 'server' : 'client';
-  const mode = Env.isProd ? 'production' : 'development';
+  const mode = isProd ? 'production' : 'development';
 
   const themeAliases = await loadThemeAliases({siteDir, plugins});
 
@@ -140,12 +131,12 @@ export async function createBaseConfig({
   }
 
   function getCache(): Configuration['cache'] {
+    if (process.env.DOCUSAURUS_NO_PERSISTENT_CACHE) {
+      // Use default: memory cache in dev, nothing in prod
+      // See https://rspack.dev/config/cache#cache
+      return undefined;
+    }
     if (props.currentBundler.name === 'rspack') {
-      if (Env.noPersistentCache) {
-        // Use default: memory cache in dev, nothing in prod
-        // See https://rspack.dev/config/cache#cache
-        return undefined;
-      }
       // Use cache: true + experiments.cache.type: "persistent"
       // See https://rspack.dev/config/experiments#persistent-cache
       return true;
@@ -162,7 +153,8 @@ export async function createBaseConfig({
 
   function getExperiments(): Configuration['experiments'] {
     if (props.currentBundler.name === 'rspack') {
-      const PersistentCacheAttributes = Env.noPersistentCache
+      const PersistentCacheAttributes = process.env
+        .DOCUSAURUS_NO_PERSISTENT_CACHE
         ? {}
         : {
             cache: {
@@ -185,7 +177,7 @@ export async function createBaseConfig({
         // See https://github.com/web-infra-dev/rspress/pull/1631
         // See https://github.com/facebook/docusaurus/issues/10646
         // @ts-expect-error: Rspack-only, not available in Webpack typedefs
-        incremental: !Env.isProd && !Env.noRspackIncremental,
+        incremental: !isProd && !process.env.DISABLE_RSPACK_INCREMENTAL,
 
         ...PersistentCacheAttributes,
       };
@@ -201,10 +193,8 @@ export async function createBaseConfig({
     output: {
       pathinfo: false,
       path: outDir,
-      filename: Env.isProd
-        ? 'assets/js/[name].[contenthash:8].js'
-        : '[name].js',
-      chunkFilename: Env.isProd
+      filename: isProd ? 'assets/js/[name].[contenthash:8].js' : '[name].js',
+      chunkFilename: isProd
         ? 'assets/js/[name].[contenthash:8].js'
         : '[name].js',
       publicPath:
@@ -215,7 +205,7 @@ export async function createBaseConfig({
     performance: {
       hints: false,
     },
-    devtool: Env.isProd ? undefined : 'eval-cheap-module-source-map',
+    devtool: isProd ? undefined : 'eval-cheap-module-source-map',
     resolve: {
       extensions: ['.wasm', '.mjs', '.js', '.jsx', '.ts', '.tsx', '.json'],
       symlinks: true, // See https://github.com/facebook/docusaurus/issues/3272
@@ -309,7 +299,7 @@ export async function createBaseConfig({
           exclude: CSS_MODULE_REGEX,
           use: configureWebpackUtils.getStyleLoaders(isServer, {
             importLoaders: 1,
-            sourceMap: !Env.isProd,
+            sourceMap: !isProd,
           }),
         },
         // Adds support for CSS Modules (https://github.com/css-modules/css-modules)
@@ -324,17 +314,17 @@ export async function createBaseConfig({
               exportOnlyLocals: isServer,
             },
             importLoaders: 1,
-            sourceMap: !Env.isProd,
+            sourceMap: !isProd,
           }),
         },
       ],
     },
     plugins: [
       new CSSExtractPlugin({
-        filename: Env.isProd
+        filename: isProd
           ? 'assets/css/[name].[contenthash:8].css'
           : '[name].css',
-        chunkFilename: Env.isProd
+        chunkFilename: isProd
           ? 'assets/css/[name].[contenthash:8].css'
           : '[name].css',
         // Remove css order warnings if css imports are not sorted

From 7eb678e8c924974ff20b8716e097ead9cba28a50 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 20 Feb 2025 13:17:22 +0100
Subject: [PATCH 11/17] bump rspack

---
 packages/docusaurus-faster/package.json |   2 +-
 yarn.lock                               | 110 ++++++++++++------------
 2 files changed, 56 insertions(+), 56 deletions(-)

diff --git a/packages/docusaurus-faster/package.json b/packages/docusaurus-faster/package.json
index 6f2870a5cc9e..cd9957735916 100644
--- a/packages/docusaurus-faster/package.json
+++ b/packages/docusaurus-faster/package.json
@@ -19,7 +19,7 @@
   "license": "MIT",
   "dependencies": {
     "@docusaurus/types": "3.7.0",
-    "@rspack/core": "^1.2.3",
+    "@rspack/core": "^1.2.5",
     "@swc/core": "^1.7.39",
     "@swc/html": "^1.7.39",
     "browserslist": "^4.24.2",
diff --git a/yarn.lock b/yarn.lock
index c4372e3502d8..3ce5da5cc02d 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -3216,73 +3216,73 @@
     fs-extra "^11.1.1"
     lodash "^4.17.21"
 
-"@rspack/binding-darwin-arm64@1.2.3":
-  version "1.2.3"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-darwin-arm64/-/binding-darwin-arm64-1.2.3.tgz#dc5d8eaff24107438182786f2e44cae5ee8a5a32"
-  integrity sha512-xuwYzhPgNCr4BtKXCU3xe4249TFsXAZglIlbxv8Qs3PeIarrZMRddcqH2zUXi+nJavNw3yN12sCYEzk1f+O4FQ==
+"@rspack/binding-darwin-arm64@1.2.5":
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-darwin-arm64/-/binding-darwin-arm64-1.2.5.tgz#69b35d70e543ac034daf0fea03d27e25112a5e8f"
+  integrity sha512-ou0NXMLp6RxY9Bx8P9lA8ArVjz/WAI/gSu5kKrdKKtMs6WKutl4vvP9A4HHZnISd9Tn00dlvDwNeNSUR7fjoDQ==
 
-"@rspack/binding-darwin-x64@1.2.3":
-  version "1.2.3"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-darwin-x64/-/binding-darwin-x64-1.2.3.tgz#5f77c8be2ae238ce8f8f5e18dbb73c399baa4deb"
-  integrity sha512-afiIN8elcrO2EtO27UN0qyZqu5FXGUdclud56DrhvEfnWS3GGxJEdjA8XUYVXkfCYakdXHucIJKlkkgaAjEvHg==
+"@rspack/binding-darwin-x64@1.2.5":
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-darwin-x64/-/binding-darwin-x64-1.2.5.tgz#22b63d233f06afb88791bec8f4fdabd020cc93f5"
+  integrity sha512-RdvH9YongQlDE9+T2Xh5D2+dyiLHx2Gz38Af1uObyBRNWjF1qbuR51hOas0f2NFUdyA03j1+HWZCbE7yZrmI3w==
 
-"@rspack/binding-linux-arm64-gnu@1.2.3":
-  version "1.2.3"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.2.3.tgz#91935de2c9b885f051675ffe4fc7cd24c3c0c8c0"
-  integrity sha512-K2u/fPUmKujlKSWL3q2zaUu8/6ZK/bOGKcqJSib8jdanQQ/GFKwKtPAFOOa/vvqbzhDocqKOobFR10FhgJqCHg==
+"@rspack/binding-linux-arm64-gnu@1.2.5":
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.2.5.tgz#19eebeeddb26802d4e6bc0f2795bdd507bb91849"
+  integrity sha512-jznk/CI/wN93fr8I1j3la/CAiGf8aG7ZHIpRBtT4CkNze0c5BcF3AaJVSBHVNQqgSv0qddxMt3SADpzV8rWZ6g==
 
-"@rspack/binding-linux-arm64-musl@1.2.3":
-  version "1.2.3"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.2.3.tgz#88c439c0aa739e29643485ae9a1b86a8a1b1e787"
-  integrity sha512-mgovdzGb6cH9hQsjTyzDbfZWCPhTcoHcLro1P7UbiqcLPMDJp/k3Io9xV2/EJhaDA1aynIdq7XfY0fuk4+6Irw==
+"@rspack/binding-linux-arm64-musl@1.2.5":
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.2.5.tgz#cf786f14621baf511f229288f873190fc4f7196b"
+  integrity sha512-oYzcaJ0xjb1fWbbtPmjjPXeehExEgwJ8fEGYQ5TikB+p9oCLkAghnNjsz9evUhgjByxi+NTZ1YmUNwxRuQDY1Q==
 
-"@rspack/binding-linux-x64-gnu@1.2.3":
-  version "1.2.3"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.2.3.tgz#083542adc8903735d1265e40c82c95046692921d"
-  integrity sha512-542lwJzB1RMGuVdBdA3cOWTlmL9okpOppHUBWcNCjmJM+9zTI+0jwjVe8HaqOqtuR8XzNsoCwT9QonU/GLcuhg==
+"@rspack/binding-linux-x64-gnu@1.2.5":
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.2.5.tgz#10082ab2550432306cf9a8b6f02042202975865c"
+  integrity sha512-dzEKs8oi86Vi+TFRCPpgmfF5ANL0VmlZN45e1An7HipeI2C5B1xrz/H8V43vPy8XEvQuMmkXO6Sp82A0zlHvIA==
 
-"@rspack/binding-linux-x64-musl@1.2.3":
-  version "1.2.3"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-x64-musl/-/binding-linux-x64-musl-1.2.3.tgz#bc2f1a857fdc613db3f113fb9088e9b73cb88dcc"
-  integrity sha512-dJromiREDcTWqzfCOI5y1IVoYmUnCv7vCp63AEq0+13fJJdk7+pcNN3VV2jOKpk9VECSvjg1c01wl+UzXAXFMw==
+"@rspack/binding-linux-x64-musl@1.2.5":
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-linux-x64-musl/-/binding-linux-x64-musl-1.2.5.tgz#0c1bef36b7789b7d3b046b6e0bdbe86944e5aca4"
+  integrity sha512-4ENeVPVSD97rRRGr6kJSm4sIPf1tKJ8vlr9hJi4sSvF7eMLWipSwIVmqRXJ2riVMRjYD2einmJ9KzI8rqQ2OwA==
 
-"@rspack/binding-win32-arm64-msvc@1.2.3":
-  version "1.2.3"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.2.3.tgz#fdca01d1ad1be84055f48b0d336a7ec651f97bc4"
-  integrity sha512-S8ZKddMMQDGy8jx/R0i2m1XrmfY2CpI+t6lIEpsuZuKUR4MbOGKN2DuL4MDnT3m8JaYvC8ihsvQjBXQCy3SNxQ==
+"@rspack/binding-win32-arm64-msvc@1.2.5":
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.2.5.tgz#70d3ab6079aa0c721dc32b989e3743a1ba59acf5"
+  integrity sha512-WUoJvX/z43MWeW1JKAQIxdvqH02oLzbaGMCzIikvniZnakQovYLPH6tCYh7qD3p7uQsm+IafFddhFxTtogC3pg==
 
-"@rspack/binding-win32-ia32-msvc@1.2.3":
-  version "1.2.3"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-1.2.3.tgz#08739da8427b251e385e800e4d4f9a5d77a58aa7"
-  integrity sha512-74lqSMKQJcJcgfFaxm+G9YVJSl2KK9/v4fRoMsWApztNy2qNgee+UguNBCOU6JLa3rVSj8Z5OVVDtJkGFrSvVg==
+"@rspack/binding-win32-ia32-msvc@1.2.5":
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-1.2.5.tgz#141e1698d1cfb7007c918cb02c1aacc89001ba35"
+  integrity sha512-YzPvmt/gpiacE6aAacz4dxgEbNWwoKYPaT4WYy/oITobnAui++iCFXC4IICSmlpoA1y7O8K3Qb9jbaB/lLhbwA==
 
-"@rspack/binding-win32-x64-msvc@1.2.3":
-  version "1.2.3"
-  resolved "https://registry.yarnpkg.com/@rspack/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.2.3.tgz#a4c445adce3b7a7d09639278b1483b2e6b4550c7"
-  integrity sha512-fcU532PgFdd5Bil8jwQW0Dcb/80oM6V0qSstGIxZ4M77t4t8e/PcukXfORTL71FfNQ64Rd4Dp6XRl1NHNJVxeg==
+"@rspack/binding-win32-x64-msvc@1.2.5":
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/@rspack/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.2.5.tgz#d1e5410784917fe8fd580805e5fc9eeef46d9822"
+  integrity sha512-QDDshfteMZiglllm7WUh/ITemFNuexwn1Yul7cHBFGQu6HqtqKNAR0kGR8J3e15MPMlinSaygVpfRE4A0KPmjQ==
 
-"@rspack/binding@1.2.3":
-  version "1.2.3"
-  resolved "https://registry.yarnpkg.com/@rspack/binding/-/binding-1.2.3.tgz#a17d0ffd5bf653f903e34a673e5b649e4eb9bfd6"
-  integrity sha512-enpOXZPQOJO800wdWcR7H5Dx5UZfwkaT0D0xsHD53WbpI09Z2KJbLX7I/i1FLLy3K1KQTB+2FIHLVdRikasXZA==
+"@rspack/binding@1.2.5":
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/@rspack/binding/-/binding-1.2.5.tgz#2038aafa0bb7899ef891437965f52634cf5ae684"
+  integrity sha512-q9vQmGDFZyFVMULwOFL7488WNSgn4ue94R/njDLMMIPF4K0oEJP2QT02elfG4KVGv2CbP63D7vEFN4ZNreo/Rw==
   optionalDependencies:
-    "@rspack/binding-darwin-arm64" "1.2.3"
-    "@rspack/binding-darwin-x64" "1.2.3"
-    "@rspack/binding-linux-arm64-gnu" "1.2.3"
-    "@rspack/binding-linux-arm64-musl" "1.2.3"
-    "@rspack/binding-linux-x64-gnu" "1.2.3"
-    "@rspack/binding-linux-x64-musl" "1.2.3"
-    "@rspack/binding-win32-arm64-msvc" "1.2.3"
-    "@rspack/binding-win32-ia32-msvc" "1.2.3"
-    "@rspack/binding-win32-x64-msvc" "1.2.3"
-
-"@rspack/core@^1.2.3":
-  version "1.2.3"
-  resolved "https://registry.yarnpkg.com/@rspack/core/-/core-1.2.3.tgz#72e76f0dc9a255759c4bcf88d40b2ff8e6a14985"
-  integrity sha512-BFgdUYf05/hjjY9Nlwq8DpWaRJN5w2kTl8ZJi20SRL60oAx+ZD2ABT+fsPhBiFSmfTZDdvGGIq5e3vfRzoIuqg==
+    "@rspack/binding-darwin-arm64" "1.2.5"
+    "@rspack/binding-darwin-x64" "1.2.5"
+    "@rspack/binding-linux-arm64-gnu" "1.2.5"
+    "@rspack/binding-linux-arm64-musl" "1.2.5"
+    "@rspack/binding-linux-x64-gnu" "1.2.5"
+    "@rspack/binding-linux-x64-musl" "1.2.5"
+    "@rspack/binding-win32-arm64-msvc" "1.2.5"
+    "@rspack/binding-win32-ia32-msvc" "1.2.5"
+    "@rspack/binding-win32-x64-msvc" "1.2.5"
+
+"@rspack/core@^1.2.5":
+  version "1.2.5"
+  resolved "https://registry.yarnpkg.com/@rspack/core/-/core-1.2.5.tgz#cefb67c1696f7003a5816d9bde2542881f6d84f7"
+  integrity sha512-x/riOl05gOVGgGQFimBqS5i8XbUpBxPIKUC+tDX4hmNNkzxRaGpspZfNtcL+1HBMyYuoM6fOWGyCp2R290Uy6g==
   dependencies:
     "@module-federation/runtime-tools" "0.8.4"
-    "@rspack/binding" "1.2.3"
+    "@rspack/binding" "1.2.5"
     "@rspack/lite-tapable" "1.0.1"
     caniuse-lite "^1.0.30001616"
 

From 6cad3992087f8351277a776a49acc965ad7e191e Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 20 Feb 2025 17:40:46 +0100
Subject: [PATCH 12/17] add rspackPersistentCache option + tests

---
 packages/docusaurus-types/src/config.d.ts     |  1 +
 .../__snapshots__/config.test.ts.snap         | 10 +++
 .../__tests__/__snapshots__/site.test.ts.snap |  1 +
 .../server/__tests__/configValidation.test.ts | 74 +++++++++++++++++++
 .../docusaurus/src/server/configValidation.ts |  5 ++
 5 files changed, 91 insertions(+)

diff --git a/packages/docusaurus-types/src/config.d.ts b/packages/docusaurus-types/src/config.d.ts
index 9c8b575a48cc..26b7022cf3d9 100644
--- a/packages/docusaurus-types/src/config.d.ts
+++ b/packages/docusaurus-types/src/config.d.ts
@@ -130,6 +130,7 @@ export type FasterConfig = {
   lightningCssMinimizer: boolean;
   mdxCrossCompilerCache: boolean;
   rspackBundler: boolean;
+  rspackPersistentCache: boolean;
   ssgWorkerThreads: boolean;
 };
 
diff --git a/packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap b/packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap
index 044bf277c4f8..1cce07a53a07 100644
--- a/packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap
+++ b/packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap
@@ -12,6 +12,7 @@ exports[`loadSiteConfig website with .cjs siteConfig 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "rspackPersistentCache": false,
         "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
@@ -85,6 +86,7 @@ exports[`loadSiteConfig website with ts + js config 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "rspackPersistentCache": false,
         "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
@@ -158,6 +160,7 @@ exports[`loadSiteConfig website with valid JS CJS config 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "rspackPersistentCache": false,
         "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
@@ -231,6 +234,7 @@ exports[`loadSiteConfig website with valid JS ESM config 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "rspackPersistentCache": false,
         "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
@@ -304,6 +308,7 @@ exports[`loadSiteConfig website with valid TypeScript CJS config 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "rspackPersistentCache": false,
         "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
@@ -377,6 +382,7 @@ exports[`loadSiteConfig website with valid TypeScript ESM config 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "rspackPersistentCache": false,
         "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
@@ -450,6 +456,7 @@ exports[`loadSiteConfig website with valid async config 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "rspackPersistentCache": false,
         "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
@@ -525,6 +532,7 @@ exports[`loadSiteConfig website with valid async config creator function 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "rspackPersistentCache": false,
         "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
@@ -600,6 +608,7 @@ exports[`loadSiteConfig website with valid config creator function 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "rspackPersistentCache": false,
         "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
@@ -678,6 +687,7 @@ exports[`loadSiteConfig website with valid siteConfig 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "rspackPersistentCache": false,
         "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
diff --git a/packages/docusaurus/src/server/__tests__/__snapshots__/site.test.ts.snap b/packages/docusaurus/src/server/__tests__/__snapshots__/site.test.ts.snap
index 341f0cc9ae5c..91aea83bc33d 100644
--- a/packages/docusaurus/src/server/__tests__/__snapshots__/site.test.ts.snap
+++ b/packages/docusaurus/src/server/__tests__/__snapshots__/site.test.ts.snap
@@ -86,6 +86,7 @@ exports[`load loads props for site with custom i18n path 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "rspackPersistentCache": false,
         "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
diff --git a/packages/docusaurus/src/server/__tests__/configValidation.test.ts b/packages/docusaurus/src/server/__tests__/configValidation.test.ts
index d99e1c8f7700..d01573d6b4de 100644
--- a/packages/docusaurus/src/server/__tests__/configValidation.test.ts
+++ b/packages/docusaurus/src/server/__tests__/configValidation.test.ts
@@ -58,6 +58,7 @@ describe('normalizeConfig', () => {
           lightningCssMinimizer: true,
           mdxCrossCompilerCache: true,
           rspackBundler: true,
+          rspackPersistentCache: true,
           ssgWorkerThreads: true,
         },
         experimental_storage: {
@@ -761,6 +762,7 @@ describe('future', () => {
         lightningCssMinimizer: true,
         mdxCrossCompilerCache: true,
         rspackBundler: true,
+        rspackPersistentCache: true,
         ssgWorkerThreads: true,
       },
       experimental_storage: {
@@ -1115,6 +1117,7 @@ describe('future', () => {
         lightningCssMinimizer: true,
         mdxCrossCompilerCache: true,
         rspackBundler: true,
+        rspackPersistentCache: true,
         ssgWorkerThreads: true,
       };
       expect(
@@ -1615,6 +1618,77 @@ describe('future', () => {
       });
     });
 
+    describe('rspackPersistentCache', () => {
+      it('accepts - undefined', () => {
+        const faster: Partial<FasterConfig> = {
+          rspackPersistentCache: undefined,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toEqual(fasterContaining({rspackPersistentCache: false}));
+      });
+
+      it('accepts - true', () => {
+        const faster: Partial<FasterConfig> = {
+          rspackPersistentCache: true,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toEqual(fasterContaining({rspackPersistentCache: true}));
+      });
+
+      it('accepts - false', () => {
+        const faster: Partial<FasterConfig> = {
+          rspackPersistentCache: false,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toEqual(fasterContaining({rspackPersistentCache: false}));
+      });
+
+      it('rejects - null', () => {
+        // @ts-expect-error: invalid
+        const faster: Partial<FasterConfig> = {rspackPersistentCache: 42};
+        expect(() =>
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toThrowErrorMatchingInlineSnapshot(`
+          ""future.experimental_faster.rspackPersistentCache" must be a boolean
+          "
+        `);
+      });
+
+      it('rejects - number', () => {
+        // @ts-expect-error: invalid
+        const faster: Partial<FasterConfig> = {rspackPersistentCache: 42};
+        expect(() =>
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toThrowErrorMatchingInlineSnapshot(`
+          ""future.experimental_faster.rspackPersistentCache" must be a boolean
+          "
+        `);
+      });
+    });
+
     describe('ssgWorkerThreads', () => {
       it('accepts - undefined', () => {
         const faster: Partial<FasterConfig> = {
diff --git a/packages/docusaurus/src/server/configValidation.ts b/packages/docusaurus/src/server/configValidation.ts
index 5b066557f04a..19217e5acb5c 100644
--- a/packages/docusaurus/src/server/configValidation.ts
+++ b/packages/docusaurus/src/server/configValidation.ts
@@ -50,6 +50,7 @@ export const DEFAULT_FASTER_CONFIG: FasterConfig = {
   lightningCssMinimizer: false,
   mdxCrossCompilerCache: false,
   rspackBundler: false,
+  rspackPersistentCache: false,
   ssgWorkerThreads: false,
 };
 
@@ -61,6 +62,7 @@ export const DEFAULT_FASTER_CONFIG_TRUE: FasterConfig = {
   lightningCssMinimizer: true,
   mdxCrossCompilerCache: true,
   rspackBundler: true,
+  rspackPersistentCache: true,
   ssgWorkerThreads: true,
 };
 
@@ -246,6 +248,9 @@ const FASTER_CONFIG_SCHEMA = Joi.alternatives()
         DEFAULT_FASTER_CONFIG.mdxCrossCompilerCache,
       ),
       rspackBundler: Joi.boolean().default(DEFAULT_FASTER_CONFIG.rspackBundler),
+      rspackPersistentCache: Joi.boolean().default(
+        DEFAULT_FASTER_CONFIG.rspackPersistentCache,
+      ),
       ssgWorkerThreads: Joi.boolean().default(
         DEFAULT_FASTER_CONFIG.ssgWorkerThreads,
       ),

From 3e65033d4af3d6101858825f0635f9921e07a1c4 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 20 Feb 2025 17:51:09 +0100
Subject: [PATCH 13/17] add edge case for rspackPersistentCache

---
 .../server/__tests__/configValidation.test.ts | 47 +++++++++++++++++--
 .../docusaurus/src/server/configValidation.ts | 16 ++++++-
 2 files changed, 57 insertions(+), 6 deletions(-)

diff --git a/packages/docusaurus/src/server/__tests__/configValidation.test.ts b/packages/docusaurus/src/server/__tests__/configValidation.test.ts
index d01573d6b4de..8d8f5058cc64 100644
--- a/packages/docusaurus/src/server/__tests__/configValidation.test.ts
+++ b/packages/docusaurus/src/server/__tests__/configValidation.test.ts
@@ -1159,7 +1159,8 @@ describe('future', () => {
         }),
       ).toThrowErrorMatchingInlineSnapshot(`
         "Docusaurus config \`future.experimental_faster.ssgWorkerThreads\` requires the future flag \`future.v4.removeLegacyPostBuildHeadAttribute\` to be turned on.
-        If you use Docusaurus Faster, we recommend that you also activate Docusaurus v4 future flags: \`{future: {v4: true}}\`"
+        If you use Docusaurus Faster, we recommend that you also activate Docusaurus v4 future flags: \`{future: {v4: true}}\`
+        All the v4 future flags are documented here: https://docusaurus.io/docs/api/docusaurus-config#future"
       `);
     });
 
@@ -1173,7 +1174,8 @@ describe('future', () => {
         }),
       ).toThrowErrorMatchingInlineSnapshot(`
         "Docusaurus config \`future.experimental_faster.ssgWorkerThreads\` requires the future flag \`future.v4.removeLegacyPostBuildHeadAttribute\` to be turned on.
-        If you use Docusaurus Faster, we recommend that you also activate Docusaurus v4 future flags: \`{future: {v4: true}}\`"
+        If you use Docusaurus Faster, we recommend that you also activate Docusaurus v4 future flags: \`{future: {v4: true}}\`
+        All the v4 future flags are documented here: https://docusaurus.io/docs/api/docusaurus-config#future"
       `);
     });
 
@@ -1632,8 +1634,9 @@ describe('future', () => {
         ).toEqual(fasterContaining({rspackPersistentCache: false}));
       });
 
-      it('accepts - true', () => {
+      it('accepts - true (rspackBundler: true)', () => {
         const faster: Partial<FasterConfig> = {
+          rspackBundler: true,
           rspackPersistentCache: true,
         };
         expect(
@@ -1645,6 +1648,38 @@ describe('future', () => {
         ).toEqual(fasterContaining({rspackPersistentCache: true}));
       });
 
+      it('rejects - true (rspackBundler: false)', () => {
+        const faster: Partial<FasterConfig> = {
+          rspackBundler: false,
+          rspackPersistentCache: true,
+        };
+        expect(() =>
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toThrowErrorMatchingInlineSnapshot(
+          `"Docusaurus config flag \`future.experimental_faster.rspackPersistentCache\` requires the flag \`future.experimental_faster.rspackBundler\` to be turned on."`,
+        );
+      });
+
+      it('rejects - true (rspackBundler: undefined)', () => {
+        const faster: Partial<FasterConfig> = {
+          rspackBundler: false,
+          rspackPersistentCache: true,
+        };
+        expect(() =>
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toThrowErrorMatchingInlineSnapshot(
+          `"Docusaurus config flag \`future.experimental_faster.rspackPersistentCache\` requires the flag \`future.experimental_faster.rspackBundler\` to be turned on."`,
+        );
+      });
+
       it('accepts - false', () => {
         const faster: Partial<FasterConfig> = {
           rspackPersistentCache: false,
@@ -1730,7 +1765,8 @@ describe('future', () => {
           }),
         ).toThrowErrorMatchingInlineSnapshot(`
           "Docusaurus config \`future.experimental_faster.ssgWorkerThreads\` requires the future flag \`future.v4.removeLegacyPostBuildHeadAttribute\` to be turned on.
-          If you use Docusaurus Faster, we recommend that you also activate Docusaurus v4 future flags: \`{future: {v4: true}}\`"
+          If you use Docusaurus Faster, we recommend that you also activate Docusaurus v4 future flags: \`{future: {v4: true}}\`
+          All the v4 future flags are documented here: https://docusaurus.io/docs/api/docusaurus-config#future"
         `);
       });
 
@@ -1747,7 +1783,8 @@ describe('future', () => {
           }),
         ).toThrowErrorMatchingInlineSnapshot(`
           "Docusaurus config \`future.experimental_faster.ssgWorkerThreads\` requires the future flag \`future.v4.removeLegacyPostBuildHeadAttribute\` to be turned on.
-          If you use Docusaurus Faster, we recommend that you also activate Docusaurus v4 future flags: \`{future: {v4: true}}\`"
+          If you use Docusaurus Faster, we recommend that you also activate Docusaurus v4 future flags: \`{future: {v4: true}}\`
+          All the v4 future flags are documented here: https://docusaurus.io/docs/api/docusaurus-config#future"
         `);
       });
 
diff --git a/packages/docusaurus/src/server/configValidation.ts b/packages/docusaurus/src/server/configValidation.ts
index 19217e5acb5c..33d7199143f6 100644
--- a/packages/docusaurus/src/server/configValidation.ts
+++ b/packages/docusaurus/src/server/configValidation.ts
@@ -471,7 +471,21 @@ function ensureDocusaurusConfigConsistency(config: DocusaurusConfig) {
       )} to be turned on.
 If you use Docusaurus Faster, we recommend that you also activate Docusaurus v4 future flags: ${logger.code(
         '{future: {v4: true}}',
-      )}`,
+      )}
+All the v4 future flags are documented here: https://docusaurus.io/docs/api/docusaurus-config#future`,
+    );
+  }
+
+  if (
+    config.future.experimental_faster.rspackPersistentCache &&
+    !config.future.experimental_faster.rspackBundler
+  ) {
+    throw new Error(
+      `Docusaurus config flag ${logger.code(
+        'future.experimental_faster.rspackPersistentCache',
+      )} requires the flag ${logger.code(
+        'future.experimental_faster.rspackBundler',
+      )} to be turned on.`,
     );
   }
 }

From 183dfef36edf6edaad010d60f387250f7c528894 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 20 Feb 2025 17:54:26 +0100
Subject: [PATCH 14/17] wire rspackPersistentCache flag

---
 packages/docusaurus/src/webpack/base.ts | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/packages/docusaurus/src/webpack/base.ts b/packages/docusaurus/src/webpack/base.ts
index 3f2b681ff792..ff00b8f79b07 100644
--- a/packages/docusaurus/src/webpack/base.ts
+++ b/packages/docusaurus/src/webpack/base.ts
@@ -131,15 +131,21 @@ export async function createBaseConfig({
   }
 
   function getCache(): Configuration['cache'] {
+    // Use default: memory cache in dev, nothing in prod
+    // See https://rspack.dev/config/cache#cache
+    const disabledPersistentCacheValue = undefined;
+
     if (process.env.DOCUSAURUS_NO_PERSISTENT_CACHE) {
-      // Use default: memory cache in dev, nothing in prod
-      // See https://rspack.dev/config/cache#cache
-      return undefined;
+      return disabledPersistentCacheValue;
     }
     if (props.currentBundler.name === 'rspack') {
-      // Use cache: true + experiments.cache.type: "persistent"
-      // See https://rspack.dev/config/experiments#persistent-cache
-      return true;
+      if (props.siteConfig.future.experimental_faster.rspackPersistentCache) {
+        // Use cache: true + experiments.cache.type: "persistent"
+        // See https://rspack.dev/config/experiments#persistent-cache
+        return true;
+      } else {
+        return disabledPersistentCacheValue;
+      }
     }
     return {
       type: 'filesystem',

From a1ee1e9ae65ec7a89fe44316ae6581bc60fd07b4 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 20 Feb 2025 17:54:33 +0100
Subject: [PATCH 15/17] wire rspackPersistentCache flag

---
 packages/docusaurus/src/webpack/base.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/docusaurus/src/webpack/base.ts b/packages/docusaurus/src/webpack/base.ts
index ff00b8f79b07..3ab34f87a97e 100644
--- a/packages/docusaurus/src/webpack/base.ts
+++ b/packages/docusaurus/src/webpack/base.ts
@@ -147,6 +147,7 @@ export async function createBaseConfig({
         return disabledPersistentCacheValue;
       }
     }
+
     return {
       type: 'filesystem',
       name: getCacheName(),

From 64ec8cd7e2279e519ef2790af4a1a8fd39ad0a02 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 20 Feb 2025 18:14:33 +0100
Subject: [PATCH 16/17] document rspackPersistentCache

---
 website/docs/api/docusaurus.config.js.mdx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/website/docs/api/docusaurus.config.js.mdx b/website/docs/api/docusaurus.config.js.mdx
index fb6bfc5a3d6c..41f5c50a9f77 100644
--- a/website/docs/api/docusaurus.config.js.mdx
+++ b/website/docs/api/docusaurus.config.js.mdx
@@ -206,6 +206,7 @@ export default {
       swcHtmlMinimizer: true,
       lightningCssMinimizer: true,
       rspackBundler: true,
+      rspackPersistentCache: true,
       ssgWorkerThreads: true,
       mdxCrossCompilerCache: true,
     },
@@ -226,6 +227,7 @@ export default {
   - [`swcHtmlMinimizer `](https://github.com/facebook/docusaurus/pull/10554): Use [SWC](https://swc.rs/) to minify HTML and inlined JS/CSS (instead of [html-minifier-terser](https://github.com/terser/html-minifier-terser)).
   - [`lightningCssMinimizer`](https://github.com/facebook/docusaurus/pull/10522): Use [Lightning CSS](https://lightningcss.dev/) to minify CSS (instead of [cssnano](https://github.com/cssnano/cssnano) and [clean-css](https://github.com/clean-css/clean-css)).
   - [`rspackBundler`](https://github.com/facebook/docusaurus/pull/10402): Use [Rspack](https://rspack.dev/) to bundle your app (instead of [webpack](https://webpack.js.org/)).
+  - [`rspackPersistentCache`](https://github.com/facebook/docusaurus/pull/10931): Use [Rspack Persistent Cache](https://rspack.dev/config/cache) to re-build your app faster on subsequent builds. Requires `rspackBundler: true`. Requires persisting `./node_modules/.cache` across rebuilds.
   - [`mdxCrossCompilerCache`](https://github.com/facebook/docusaurus/pull/10479): Compile MDX files only once for both browser/Node.js environments instead of twice.
   - [`ssgWorkerThreads`](https://github.com/facebook/docusaurus/pull/10826): Using a Node.js worker thread pool to execute the static site generation phase faster. Requires `future.v4.removeLegacyPostBuildHeadAttribute` to be turned on.
 - `experimental_storage`: Site-wide browser storage options that theme authors should strive to respect.

From c80d5e688cd37c4744ba8ba9d731e3c82842e5e6 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 20 Feb 2025 18:54:15 +0100
Subject: [PATCH 17/17] temporarily disable createMdxLoaderDependencyFile

---
 packages/docusaurus-plugin-content-docs/src/index.ts | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts
index 0d39e04e54ea..a774c2b52c47 100644
--- a/packages/docusaurus-plugin-content-docs/src/index.ts
+++ b/packages/docusaurus-plugin-content-docs/src/index.ts
@@ -76,7 +76,14 @@ async function createMdxLoaderDependencyFile({
   dataDir: string;
   options: PluginOptions;
   versionsMetadata: VersionMetadata[];
-}) {
+}): Promise<string | undefined> {
+  // TODO this has been temporarily made opt-in until Rspack cache bug is fixed
+  //  See https://github.com/facebook/docusaurus/pull/10931
+  //  See https://github.com/facebook/docusaurus/pull/10934#issuecomment-2672253145
+  if (!process.env.DOCUSAURUS_ENABLE_MDX_DEPENDENCY_FILE) {
+    return undefined;
+  }
+
   const filePath = path.join(dataDir, '__mdx-loader-dependency.json');
   // the cache is invalidated whenever this file content changes
   const fileContent = {
@@ -138,7 +145,7 @@ export default async function pluginContentDocs(
             options,
             versionsMetadata,
           }),
-        ],
+        ].filter((d): d is string => typeof d === 'string'),
 
         useCrossCompilerCache:
           siteConfig.future.experimental_faster.mdxCrossCompilerCache,