feat(core): Docusaurus Faster - Rspack Persistent Cache

.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

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.5",
     "@swc/core": "^1.7.39",
     "@swc/html": "^1.7.39",
     "browserslist": "^4.24.2",

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,

packages/docusaurus-types/src/config.d.ts

@@ -130,6 +130,7 @@ export type FasterConfig = {
   lightningCssMinimizer: boolean;
   mdxCrossCompilerCache: boolean;
   rspackBundler: boolean;
+  rspackPersistentCache: boolean;
   ssgWorkerThreads: boolean;
 };
 

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

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,

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(
@@ -1156,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"
       `);
     });
 
@@ -1170,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"
       `);
     });
 
@@ -1615,6 +1620,110 @@ 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 (rspackBundler: true)', () => {
+        const faster: Partial<FasterConfig> = {
+          rspackBundler: true,
+          rspackPersistentCache: true,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).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,
+        };
+        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> = {
@@ -1656,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"
         `);
       });
 
@@ -1673,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"
         `);
       });