feat(core): Docusaurus Faster is stable + v4 future flag turns it on by default

admin/scripts/test-release.sh

@@ -10,7 +10,7 @@ set -xeuo pipefail
 rm -rf ../test-website
 
 CUSTOM_REGISTRY_URL="http://localhost:4873"
-NEW_VERSION="$(node -p "require('./packages/docusaurus/package.json').version")-NEW"
+NEW_VERSION="$(node -p "require('./packages/docusaurus/package.json').version")-NEW-$RANDOM"
 CONTAINER_NAME="verdaccio"
 EXTRA_OPTS=""
 

packages/create-docusaurus/templates/classic-typescript/package.json

@@ -16,6 +16,7 @@
   },
   "dependencies": {
     "@docusaurus/core": "3.9.2",
+    "@docusaurus/faster": "3.9.2",
     "@docusaurus/preset-classic": "3.9.2",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",

packages/create-docusaurus/templates/classic/package.json

@@ -15,6 +15,7 @@
   },
   "dependencies": {
     "@docusaurus/core": "3.9.2",
+    "@docusaurus/faster": "3.9.2",
     "@docusaurus/preset-classic": "3.9.2",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",

packages/docusaurus-bundler/src/currentBundler.ts

@@ -16,15 +16,12 @@ import type {CurrentBundler, DocusaurusConfig} from '@docusaurus/types';
 // We inject a site config slice because the Rspack flag might change place
 type SiteConfigSlice = {
   future: {
-    experimental_faster: Pick<
-      DocusaurusConfig['future']['experimental_faster'],
-      'rspackBundler'
-    >;
+    faster: Pick<DocusaurusConfig['future']['faster'], 'rspackBundler'>;
   };
 };
 
 function isRspack(siteConfig: SiteConfigSlice): boolean {
-  return siteConfig.future.experimental_faster.rspackBundler;
+  return siteConfig.future.faster.rspackBundler;
 }
 
 export async function getCurrentBundler({

packages/docusaurus-bundler/src/loaders/__tests__/jsLoader.test.ts

@@ -25,8 +25,8 @@ describe('createJsLoaderFactory', () => {
         webpack: siteConfig?.webpack,
         future: fromPartial({
           ...siteConfig?.future,
-          experimental_faster: fromPartial({
-            ...siteConfig?.future?.experimental_faster,
+          faster: fromPartial({
+            ...siteConfig?.future?.faster,
           }),
         }),
       },
@@ -71,7 +71,7 @@ describe('createJsLoaderFactory', () => {
     await expect(() =>
       testJsLoaderFactory({
         future: {
-          experimental_faster: {
+          faster: {
             swcJsLoader: true,
           },
         },
@@ -82,10 +82,10 @@ describe('createJsLoaderFactory', () => {
         },
       }),
     ).rejects.toThrowErrorMatchingInlineSnapshot(`
-      "You can't use siteConfig.webpack.jsLoader and siteConfig.future.experimental_faster.swcJsLoader at the same time.
+      "You can't use siteConfig.webpack.jsLoader and siteConfig.future.faster.swcJsLoader at the same time.
       To avoid any configuration ambiguity, you must make an explicit choice:
       - If you want to use Docusaurus Faster and SWC (recommended), remove siteConfig.webpack.jsLoader
-      - If you want to use a custom JS loader, use siteConfig.future.experimental_faster.swcJsLoader: false"
+      - If you want to use a custom JS loader, use siteConfig.future.faster.swcJsLoader: false"
     `);
   });
 

packages/docusaurus-bundler/src/loaders/jsLoader.ts

@@ -56,19 +56,19 @@ export async function createJsLoaderFactory({
   siteConfig: {
     webpack?: DocusaurusConfig['webpack'];
     future: {
-      experimental_faster: DocusaurusConfig['future']['experimental_faster'];
+      faster: DocusaurusConfig['future']['faster'];
     };
   };
 }): Promise<ConfigureWebpackUtils['getJSLoader']> {
   const currentBundler = await getCurrentBundler({siteConfig});
-  const isSWCLoader = siteConfig.future.experimental_faster.swcJsLoader;
+  const isSWCLoader = siteConfig.future.faster.swcJsLoader;
   if (isSWCLoader) {
     if (siteConfig.webpack?.jsLoader) {
       throw new Error(
-        `You can't use siteConfig.webpack.jsLoader and siteConfig.future.experimental_faster.swcJsLoader at the same time.
+        `You can't use siteConfig.webpack.jsLoader and siteConfig.future.faster.swcJsLoader at the same time.
 To avoid any configuration ambiguity, you must make an explicit choice:
 - If you want to use Docusaurus Faster and SWC (recommended), remove siteConfig.webpack.jsLoader
-- If you want to use a custom JS loader, use siteConfig.future.experimental_faster.swcJsLoader: false`,
+- If you want to use a custom JS loader, use siteConfig.future.faster.swcJsLoader: false`,
       );
     }
     return currentBundler.name === 'rspack'

packages/docusaurus-plugin-content-blog/src/index.ts

@@ -118,8 +118,7 @@ export default async function pluginContentBlog(
     const contentDirs = getContentPathList(contentPaths);
 
     const mdxLoaderItem = await createMDXLoaderItem({
-      useCrossCompilerCache:
-        siteConfig.future.experimental_faster.mdxCrossCompilerCache,
+      useCrossCompilerCache: siteConfig.future.faster.mdxCrossCompilerCache,
       admonitions,
       remarkPlugins,
       rehypePlugins,

packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts

@@ -330,7 +330,7 @@ describe('simple website', () => {
       configureWebpackUtils: await createConfigureWebpackUtils({
         siteConfig: {
           webpack: {jsLoader: 'babel'},
-          future: {experimental_faster: fromPartial({})},
+          future: {faster: fromPartial({})},
         },
       }),
       content,

packages/docusaurus-plugin-content-docs/src/index.ts

@@ -131,8 +131,7 @@ export default async function pluginContentDocs(
           }),
         ].filter((d): d is string => typeof d === 'string'),
 
-        useCrossCompilerCache:
-          siteConfig.future.experimental_faster.mdxCrossCompilerCache,
+        useCrossCompilerCache: siteConfig.future.faster.mdxCrossCompilerCache,
         admonitions: options.admonitions,
         remarkPlugins,
         rehypePlugins,

packages/docusaurus-plugin-content-pages/src/index.ts

@@ -58,8 +58,7 @@ export default async function pluginContentPages(
         // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
         .map(addTrailingPathSeparator),
       options: {
-        useCrossCompilerCache:
-          siteConfig.future.experimental_faster.mdxCrossCompilerCache,
+        useCrossCompilerCache: siteConfig.future.faster.mdxCrossCompilerCache,
         admonitions,
         remarkPlugins,
         rehypePlugins,

packages/docusaurus-plugin-pwa/src/index.ts

@@ -157,7 +157,7 @@ export default function pluginPWA(
           minimizer: debug
             ? []
             : await getMinimizers({
-                faster: props.siteConfig.future.experimental_faster,
+                faster: props.siteConfig.future.faster,
                 currentBundler: props.currentBundler,
               }),
         },

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

@@ -40,6 +40,7 @@ export type FutureV4Config = {
   removeLegacyPostBuildHeadAttribute: boolean;
   useCssCascadeLayers: boolean;
   siteStorageNamespacing: boolean;
+  fasterByDefault: boolean;
 };
 
 // VCS (Version Control System) info about a given change, e.g., a git commit.
@@ -95,7 +96,7 @@ export type FutureConfig = {
    */
   v4: FutureV4Config;
 
-  experimental_faster: FasterConfig;
+  faster: FasterConfig;
 
   experimental_vcs: VcsConfig;
 
@@ -421,7 +422,7 @@ export type Config = Overwrite<
       DeepPartial<FutureConfig>,
       {
         v4?: boolean | Partial<FutureV4Config>;
-        experimental_faster?: boolean | Partial<FasterConfig>;
+        faster?: boolean | Partial<FasterConfig>;
         experimental_vcs?: VcsPreset | VcsConfig | boolean;
       }
     >;

packages/docusaurus/package.json

@@ -90,10 +90,16 @@
     "tree-node-cli": "^1.6.0"
   },
   "peerDependencies": {
+    "@docusaurus/faster": "*",
     "@mdx-js/react": "^3.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "@docusaurus/faster": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=20.0"
   }

packages/docusaurus/src/commands/build/buildLocale.ts

@@ -217,7 +217,7 @@ async function getBuildClientConfig({
   const result = await createBuildClientConfig({
     props,
     minify: cliOptions.minify ?? true,
-    faster: props.siteConfig.future.experimental_faster,
+    faster: props.siteConfig.future.faster,
     configureWebpackUtils,
     bundleAnalyzer: cliOptions.bundleAnalyzer ?? false,
   });

packages/docusaurus/src/commands/start/webpack.ts

@@ -134,7 +134,7 @@ async function getStartClientConfig({
   let {clientConfig: config} = await createStartClientConfig({
     props,
     minify,
-    faster: props.siteConfig.future.experimental_faster,
+    faster: props.siteConfig.future.faster,
     poll,
     configureWebpackUtils,
   });