feat(core): Docusaurus Faster - SSG worker threads (#10826)

Co-authored-by: Sébastien Lorber <[email protected]> Co-authored-by: Mariusz Krzaczkowski <[email protected]> Co-authored-by: João Victor Lopes <[email protected]> Co-authored-by: slorber <[email protected]>
facebook · Jan 27, 2025 · 98aab81 · 98aab81
1 parent 042070c
commit 98aab81
Show file tree

Hide file tree

Showing 18 changed files with 767 additions and 204 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -21,6 +21,7 @@
   ],
   "ignorePaths": [
     "CHANGELOG.md",
+    "patches",
     "packages/docusaurus-theme-translations/locales",
     "package.json",
     "yarn.lock",

diff --git a/package.json b/package.json
@@ -50,7 +50,7 @@
     "canary:bumpVersion": "yarn lerna version `yarn --silent canary:version` --exact --no-push --yes",
     "canary:publish": "yarn lerna publish from-package --dist-tag canary --yes --no-verify-access",
     "changelog": "lerna-changelog",
-    "postinstall": "yarn lock:update && yarn build:packages",
+    "postinstall": "patch-package && yarn lock:update && yarn build:packages",
     "prepare": "husky install",
     "format": "prettier --write .",
     "format:diff": "prettier --list-different .",
@@ -112,6 +112,8 @@
     "lint-staged": "~13.2.3",
     "lockfile-lint": "^4.14.0",
     "npm-run-all": "^4.1.5",
+    "patch-package": "^8.0.0",
+    "postinstall-postinstall": "^2.1.0",
     "prettier": "^2.8.8",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",

diff --git 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;
+  ssgWorkerThreads: boolean;
 };
 
 export type FutureV4Config = {

diff --git a/packages/docusaurus/package.json b/packages/docusaurus/package.json
@@ -69,6 +69,7 @@
     "semver": "^7.5.4",
     "serve-handler": "^6.1.6",
     "shelljs": "^0.8.5",
+    "tinypool": "^1.0.2",
     "tslib": "^2.6.0",
     "update-notifier": "^6.0.2",
     "webpack": "^5.95.0",

diff --git 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,
+        "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
@@ -84,6 +85,7 @@ exports[`loadSiteConfig website with ts + js config 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
@@ -156,6 +158,7 @@ exports[`loadSiteConfig website with valid JS CJS config 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
@@ -228,6 +231,7 @@ exports[`loadSiteConfig website with valid JS ESM config 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
@@ -300,6 +304,7 @@ exports[`loadSiteConfig website with valid TypeScript CJS config 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
@@ -372,6 +377,7 @@ exports[`loadSiteConfig website with valid TypeScript ESM config 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
@@ -444,6 +450,7 @@ exports[`loadSiteConfig website with valid async config 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
@@ -518,6 +525,7 @@ exports[`loadSiteConfig website with valid async config creator function 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
@@ -592,6 +600,7 @@ exports[`loadSiteConfig website with valid config creator function 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
@@ -669,6 +678,7 @@ exports[`loadSiteConfig website with valid siteConfig 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
         "swcJsMinimizer": 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
@@ -86,6 +86,7 @@ exports[`load loads props for site with custom i18n path 1`] = `
         "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
+        "ssgWorkerThreads": false,
         "swcHtmlMinimizer": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,

diff --git 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,
+          ssgWorkerThreads: true,
         },
         experimental_storage: {
           type: 'sessionStorage',
@@ -760,6 +761,7 @@ describe('future', () => {
         lightningCssMinimizer: true,
         mdxCrossCompilerCache: true,
         rspackBundler: true,
+        ssgWorkerThreads: true,
       },
       experimental_storage: {
         type: 'sessionStorage',
@@ -1113,10 +1115,12 @@ describe('future', () => {
         lightningCssMinimizer: true,
         mdxCrossCompilerCache: true,
         rspackBundler: true,
+        ssgWorkerThreads: true,
       };
       expect(
         normalizeConfig({
           future: {
+            v4: true,
             experimental_faster: faster,
           },
         }),
@@ -1131,14 +1135,45 @@ describe('future', () => {
       ).toEqual(fasterContaining(DEFAULT_FASTER_CONFIG));
     });
 
-    it('accepts faster - true', () => {
+    it('accepts faster - true (v4: true)', () => {
       expect(
         normalizeConfig({
-          future: {experimental_faster: true},
+          future: {
+            v4: true,
+            experimental_faster: true,
+          },
         }),
       ).toEqual(fasterContaining(DEFAULT_FASTER_CONFIG_TRUE));
     });
 
+    it('rejects faster - true (v4: false)', () => {
+      expect(() =>
+        normalizeConfig({
+          future: {
+            v4: false,
+            experimental_faster: true,
+          },
+        }),
+      ).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}}\`"
+      `);
+    });
+
+    it('rejects faster - true (v4: undefined)', () => {
+      expect(() =>
+        normalizeConfig({
+          future: {
+            v4: false,
+            experimental_faster: true,
+          },
+        }),
+      ).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}}\`"
+      `);
+    });
+
     it('rejects faster - number', () => {
       // @ts-expect-error: invalid
       const faster: Partial<FasterConfig> = 42;
@@ -1579,6 +1614,112 @@ describe('future', () => {
         `);
       });
     });
+
+    describe('ssgWorkerThreads', () => {
+      it('accepts - undefined', () => {
+        const faster: Partial<FasterConfig> = {
+          ssgWorkerThreads: undefined,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toEqual(fasterContaining({ssgWorkerThreads: false}));
+      });
+
+      it('accepts - true (v4: true)', () => {
+        const faster: Partial<FasterConfig> = {
+          ssgWorkerThreads: true,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              v4: true,
+              experimental_faster: faster,
+            },
+          }),
+        ).toEqual(fasterContaining({ssgWorkerThreads: true}));
+      });
+
+      it('rejects - true (v4: false)', () => {
+        const faster: Partial<FasterConfig> = {
+          ssgWorkerThreads: true,
+        };
+        expect(() =>
+          normalizeConfig({
+            future: {
+              v4: false,
+              experimental_faster: faster,
+            },
+          }),
+        ).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}}\`"
+        `);
+      });
+
+      it('rejects - true (v4: undefined)', () => {
+        const faster: Partial<FasterConfig> = {
+          ssgWorkerThreads: true,
+        };
+        expect(() =>
+          normalizeConfig({
+            future: {
+              v4: undefined,
+              experimental_faster: faster,
+            },
+          }),
+        ).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}}\`"
+        `);
+      });
+
+      it('accepts - false', () => {
+        const faster: Partial<FasterConfig> = {
+          ssgWorkerThreads: false,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toEqual(fasterContaining({ssgWorkerThreads: false}));
+      });
+
+      it('rejects - null', () => {
+        // @ts-expect-error: invalid
+        const faster: Partial<FasterConfig> = {ssgWorkerThreads: 42};
+        expect(() =>
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toThrowErrorMatchingInlineSnapshot(`
+          ""future.experimental_faster.ssgWorkerThreads" must be a boolean
+          "
+        `);
+      });
+
+      it('rejects - number', () => {
+        // @ts-expect-error: invalid
+        const faster: Partial<FasterConfig> = {ssgWorkerThreads: 42};
+        expect(() =>
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toThrowErrorMatchingInlineSnapshot(`
+          ""future.experimental_faster.ssgWorkerThreads" must be a boolean
+          "
+        `);
+      });
+    });
   });
 
   describe('v4', () => {

diff --git a/packages/docusaurus/src/server/configValidation.ts b/packages/docusaurus/src/server/configValidation.ts
@@ -16,6 +16,7 @@ import {
   addLeadingSlash,
   removeTrailingSlash,
 } from '@docusaurus/utils-common';
+import logger from '@docusaurus/logger';
 import type {
   FasterConfig,
   FutureConfig,
@@ -49,6 +50,7 @@ export const DEFAULT_FASTER_CONFIG: FasterConfig = {
   lightningCssMinimizer: false,
   mdxCrossCompilerCache: false,
   rspackBundler: false,
+  ssgWorkerThreads: false,
 };
 
 // When using the "faster: true" shortcut
@@ -59,6 +61,7 @@ export const DEFAULT_FASTER_CONFIG_TRUE: FasterConfig = {
   lightningCssMinimizer: true,
   mdxCrossCompilerCache: true,
   rspackBundler: true,
+  ssgWorkerThreads: true,
 };
 
 export const DEFAULT_FUTURE_V4_CONFIG: FutureV4Config = {
@@ -243,6 +246,9 @@ const FASTER_CONFIG_SCHEMA = Joi.alternatives()
         DEFAULT_FASTER_CONFIG.mdxCrossCompilerCache,
       ),
       rspackBundler: Joi.boolean().default(DEFAULT_FASTER_CONFIG.rspackBundler),
+      ssgWorkerThreads: Joi.boolean().default(
+        DEFAULT_FASTER_CONFIG.ssgWorkerThreads,
+      ),
     }),
     Joi.boolean()
       .required()
@@ -445,6 +451,26 @@ export const ConfigSchema = Joi.object<DocusaurusConfig>({
     'Docusaurus config validation warning. Field {#label}: {#warningMessage}',
 });
 
+// Expressing this kind of logic in Joi is a pain
+// We also want to decouple logic from Joi: easier to remove it later!
+function ensureDocusaurusConfigConsistency(config: DocusaurusConfig) {
+  if (
+    config.future.experimental_faster.ssgWorkerThreads &&
+    !config.future.v4.removeLegacyPostBuildHeadAttribute
+  ) {
+    throw new Error(
+      `Docusaurus config ${logger.code(
+        'future.experimental_faster.ssgWorkerThreads',
+      )} requires the future flag ${logger.code(
+        'future.v4.removeLegacyPostBuildHeadAttribute',
+      )} to be turned on.
+If you use Docusaurus Faster, we recommend that you also activate Docusaurus v4 future flags: ${logger.code(
+        '{future: {v4: true}}',
+      )}`,
+    );
+  }
+}
+
 // TODO move to @docusaurus/utils-validation
 export function validateConfig(
   config: unknown,
@@ -476,7 +502,9 @@ export function validateConfig(
       ? `${formattedError}These field(s) (${unknownFields}) are not recognized in ${siteConfigPath}.\nIf you still want these fields to be in your configuration, put them in the "customFields" field.\nSee https://docusaurus.io/docs/api/docusaurus-config/#customfields`
       : formattedError;
     throw new Error(formattedError);
-  } else {
-    return value;
   }
+
+  ensureDocusaurusConfigConsistency(value);
+
+  return value;
 }