add v4 future flag: enableSSGWorkerThreads

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

@@ -134,6 +134,7 @@ export type FasterConfig = {
 
 export type FutureV4Config = {
   removeLegacyPostBuildHeadAttribute: boolean;
+  enableSSGWorkerThreads: boolean;
 };
 
 export type FutureConfig = {

packages/docusaurus/src/server/__tests__/configValidation.test.ts

@@ -50,6 +50,7 @@ describe('normalizeConfig', () => {
       future: {
         v4: {
           removeLegacyPostBuildHeadAttribute: true,
+          enableSSGWorkerThreads: true,
         },
         experimental_faster: {
           swcJsLoader: true,
@@ -752,6 +753,7 @@ describe('future', () => {
     const future: DocusaurusConfig['future'] = {
       v4: {
         removeLegacyPostBuildHeadAttribute: true,
+        enableSSGWorkerThreads: true,
       },
       experimental_faster: {
         swcJsLoader: true,
@@ -1609,6 +1611,7 @@ describe('future', () => {
     it('accepts v4 - full', () => {
       const v4: FutureV4Config = {
         removeLegacyPostBuildHeadAttribute: true,
+        enableSSGWorkerThreads: true,
       };
       expect(
         normalizeConfig({
@@ -1724,5 +1727,115 @@ describe('future', () => {
         `);
       });
     });
+
+    describe('enableSSGWorkerThreads', () => {
+      it('accepts - undefined', () => {
+        const v4: Partial<FutureV4Config> = {
+          enableSSGWorkerThreads: undefined,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              v4,
+            },
+          }),
+        ).toEqual(v4Containing({enableSSGWorkerThreads: false}));
+      });
+
+      it('accepts - true', () => {
+        const v4: Partial<FutureV4Config> = {
+          removeLegacyPostBuildHeadAttribute: true, // required dependency
+          enableSSGWorkerThreads: true,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              v4,
+            },
+          }),
+        ).toEqual(v4Containing({enableSSGWorkerThreads: true}));
+      });
+
+      it('accepts - false', () => {
+        const v4: Partial<FutureV4Config> = {
+          enableSSGWorkerThreads: false,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              v4,
+            },
+          }),
+        ).toEqual(v4Containing({enableSSGWorkerThreads: false}));
+      });
+
+      it('rejects - true if removeLegacyPostBuildHeadAttribute is false', () => {
+        const v4: Partial<FutureV4Config> = {
+          removeLegacyPostBuildHeadAttribute: false,
+          enableSSGWorkerThreads: true,
+        };
+        expect(() =>
+          normalizeConfig({
+            future: {
+              v4,
+            },
+          }),
+        ).toThrowErrorMatchingInlineSnapshot(`
+          "Docusaurus v4 future flag \`enableSSGWorkerThreads\` requires \`removeLegacyPostBuildHeadAttribute\` to be enabled first.
+          "
+        `);
+      });
+
+      it('rejects - true if removeLegacyPostBuildHeadAttribute is undefined', () => {
+        const v4: Partial<FutureV4Config> = {
+          removeLegacyPostBuildHeadAttribute: undefined,
+          enableSSGWorkerThreads: true,
+        };
+        expect(() =>
+          normalizeConfig({
+            future: {
+              v4,
+            },
+          }),
+        ).toThrowErrorMatchingInlineSnapshot(`
+          "Docusaurus v4 future flag \`enableSSGWorkerThreads\` requires \`removeLegacyPostBuildHeadAttribute\` to be enabled first.
+          "
+        `);
+      });
+
+      it('rejects - null', () => {
+        const v4: Partial<FutureV4Config> = {
+          // @ts-expect-error: invalid
+          enableSSGWorkerThreads: 42,
+        };
+        expect(() =>
+          normalizeConfig({
+            future: {
+              v4,
+            },
+          }),
+        ).toThrowErrorMatchingInlineSnapshot(`
+          ""future.v4.enableSSGWorkerThreads" must be a boolean
+          "
+        `);
+      });
+
+      it('rejects - number', () => {
+        const v4: Partial<FutureV4Config> = {
+          // @ts-expect-error: invalid
+          enableSSGWorkerThreads: 42,
+        };
+        expect(() =>
+          normalizeConfig({
+            future: {
+              v4,
+            },
+          }),
+        ).toThrowErrorMatchingInlineSnapshot(`
+          ""future.v4.enableSSGWorkerThreads" must be a boolean
+          "
+        `);
+      });
+    });
   });
 });

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,
@@ -63,11 +64,13 @@ export const DEFAULT_FASTER_CONFIG_TRUE: FasterConfig = {
 
 export const DEFAULT_FUTURE_V4_CONFIG: FutureV4Config = {
   removeLegacyPostBuildHeadAttribute: false,
+  enableSSGWorkerThreads: false,
 };
 
 // When using the "v4: true" shortcut
 export const DEFAULT_FUTURE_V4_CONFIG_TRUE: FutureV4Config = {
   removeLegacyPostBuildHeadAttribute: true,
+  enableSSGWorkerThreads: true,
 };
 
 export const DEFAULT_FUTURE_CONFIG: FutureConfig = {
@@ -259,6 +262,27 @@ const FUTURE_V4_SCHEMA = Joi.alternatives()
       removeLegacyPostBuildHeadAttribute: Joi.boolean().default(
         DEFAULT_FUTURE_V4_CONFIG.removeLegacyPostBuildHeadAttribute,
       ),
+      enableSSGWorkerThreads: Joi.boolean()
+        .default(DEFAULT_FUTURE_V4_CONFIG.enableSSGWorkerThreads)
+        .custom((value, helpers) => {
+          const {removeLegacyPostBuildHeadAttribute} =
+            helpers.state.ancestors[0];
+          if (
+            value === true &&
+            (removeLegacyPostBuildHeadAttribute === false ||
+              removeLegacyPostBuildHeadAttribute === undefined)
+          ) {
+            return helpers.error('any.custom', {key: 'B'});
+          }
+          return value; // Return the valid value
+        })
+        .messages({
+          'any.custom': `Docusaurus v4 future flag ${logger.code(
+            'enableSSGWorkerThreads',
+          )} requires ${logger.code(
+            'removeLegacyPostBuildHeadAttribute',
+          )} to be enabled first.`,
+        }),
     }),
     Joi.boolean()
       .required()