feat(core): Docusaurus Faster - Rspack Persistent Cache

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",

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: 'Webpack persistent cache folder',
+    description: 'bundler persistent cache folder',
   }));
   await Promise.all(
     [generatedFolder, buildFolder, ...cacheFolders].map(removePath),

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}`,
     );
   }
 

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 {
@@ -35,9 +39,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 +101,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});
 
@@ -103,19 +116,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}-${DOCUSAURUS_VERSION}`;
+  }
+
+  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,
@@ -127,20 +158,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
@@ -150,7 +185,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 && !process.env.DISABLE_RSPACK_INCREMENTAL,
+        incremental: !Env.isProd && !Env.noRspackIncremental,
+
+        ...PersistentCacheAttributes,
       };
     }
     return undefined;
@@ -164,8 +201,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 +215,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 +309,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 +324,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

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"