refactor(core): prepare codebase for swappable bundler

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

@@ -21,6 +21,7 @@ import {sortRoutes} from '@docusaurus/core/src/server/plugins/routeConfig';
 import {posixPath} from '@docusaurus/utils';
 import {normalizePluginOptions} from '@docusaurus/utils-validation';
 
+import {fromPartial} from '@total-typescript/shoehorn';
 import pluginContentDocs from '../index';
 import {toSidebarsProp} from '../props';
 import {DefaultSidebarItemsGenerator} from '../sidebars/generator';
@@ -288,8 +289,11 @@ describe('simple website', () => {
         },
       },
       isServer: false,
-      utils: createConfigureWebpackUtils({
-        siteConfig: {webpack: {jsLoader: 'babel'}},
+      configureWebpackUtils: await createConfigureWebpackUtils({
+        siteConfig: {
+          webpack: {jsLoader: 'babel'},
+          future: {experimental_faster: fromPartial({})},
+        },
       }),
       content,
     });

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

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type webpack from 'webpack';
+
+// We use Webpack and Rspack interchangeably because most Rspack APIs are
+// compatible with Webpack. So it's ok to use Webpack types for Rspack too.
+// When compatibility doesn't work, use "CurrentBundler.name"
+// See https://github.com/facebook/docusaurus/pull/10402
+export type CurrentBundler = {
+  name: 'webpack' | 'rspack';
+  instance: typeof webpack;
+};

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

@@ -127,6 +127,7 @@ export type FasterConfig = {
   swcJsLoader: boolean;
   swcJsMinimizer: boolean;
   mdxCrossCompilerCache: boolean;
+  rspackBundler: boolean;
 };
 
 export type FutureConfig = {

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

@@ -73,6 +73,8 @@ export {
   HtmlTags,
 } from './plugin';
 
+export {CurrentBundler} from './bundler';
+
 export {
   RouteConfig,
   PluginRouteConfig,

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

@@ -15,6 +15,7 @@ import type {ThemeConfig} from './config';
 import type {LoadContext, Props} from './context';
 import type {SwizzleConfig} from './swizzle';
 import type {RouteConfig} from './routing';
+import type {CurrentBundler} from './bundler';
 
 export type PluginOptions = {id?: string} & {[key: string]: unknown};
 
@@ -54,6 +55,7 @@ export type PluginContentLoadedActions = {
 };
 
 export type ConfigureWebpackUtils = {
+  currentBundler: CurrentBundler;
   getStyleLoaders: (
     isServer: boolean,
     cssOptions: {[key: string]: unknown},
@@ -130,7 +132,7 @@ export type Plugin<Content = unknown> = {
   configureWebpack?: (
     config: WebpackConfiguration,
     isServer: boolean,
-    utils: ConfigureWebpackUtils,
+    configureWebpackUtils: ConfigureWebpackUtils,
     content: Content,
   ) => WebpackConfiguration & {
     mergeStrategy?: {

packages/docusaurus/src/commands/build.ts

@@ -34,7 +34,12 @@ import defaultSSRTemplate from '../templates/ssr.html.template';
 import type {SSGParams} from '../ssg';
 
 import type {Manifest} from 'react-loadable-ssr-addon-v5-slorber';
-import type {LoadedPlugin, Props, RouterType} from '@docusaurus/types';
+import type {
+  ConfigureWebpackUtils,
+  LoadedPlugin,
+  Props,
+  RouterType,
+} from '@docusaurus/types';
 import type {SiteCollectedData} from '../common';
 
 export type BuildCLIOptions = Pick<
@@ -165,16 +170,20 @@ async function buildLocale({
 
   const router = siteConfig.future.experimental_router;
 
+  const configureWebpackUtils = await createConfigureWebpackUtils({siteConfig});
+
   // We can build the 2 configs in parallel
   const [{clientConfig, clientManifestPath}, {serverConfig, serverBundlePath}] =
     await PerfLogger.async('Creating webpack configs', () =>
       Promise.all([
         getBuildClientConfig({
           props,
           cliOptions,
+          configureWebpackUtils,
         }),
         getBuildServerConfig({
           props,
+          configureWebpackUtils,
         }),
       ]),
     );
@@ -324,42 +333,48 @@ async function executeBrokenLinksCheck({
 async function getBuildClientConfig({
   props,
   cliOptions,
+  configureWebpackUtils,
 }: {
   props: Props;
   cliOptions: BuildCLIOptions;
+  configureWebpackUtils: ConfigureWebpackUtils;
 }) {
   const {plugins} = props;
   const result = await createBuildClientConfig({
     props,
     minify: cliOptions.minify ?? true,
     faster: props.siteConfig.future.experimental_faster,
+    configureWebpackUtils,
     bundleAnalyzer: cliOptions.bundleAnalyzer ?? false,
   });
   let {config} = result;
   config = executePluginsConfigureWebpack({
     plugins,
     config,
     isServer: false,
-    utils: await createConfigureWebpackUtils({
-      siteConfig: props.siteConfig,
-    }),
+    configureWebpackUtils,
   });
   return {clientConfig: config, clientManifestPath: result.clientManifestPath};
 }
 
-async function getBuildServerConfig({props}: {props: Props}) {
+async function getBuildServerConfig({
+  props,
+  configureWebpackUtils,
+}: {
+  props: Props;
+  configureWebpackUtils: ConfigureWebpackUtils;
+}) {
   const {plugins} = props;
   const result = await createServerConfig({
     props,
+    configureWebpackUtils,
   });
   let {config} = result;
   config = executePluginsConfigureWebpack({
     plugins,
     config,
     isServer: true,
-    utils: await createConfigureWebpackUtils({
-      siteConfig: props.siteConfig,
-    }),
+    configureWebpackUtils,
   });
   return {serverConfig: config, serverBundlePath: result.serverBundlePath};
 }

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

@@ -23,7 +23,7 @@ import {
 } from '../../webpack/configure';
 import {createStartClientConfig} from '../../webpack/client';
 import type {StartCLIOptions} from './start';
-import type {Props} from '@docusaurus/types';
+import type {ConfigureWebpackUtils, Props} from '@docusaurus/types';
 import type {Compiler} from 'webpack';
 import type {OpenUrlContext} from './utils';
 
@@ -127,23 +127,26 @@ async function getStartClientConfig({
   props,
   minify,
   poll,
+  configureWebpackUtils,
 }: {
   props: Props;
   minify: boolean;
   poll: number | boolean | undefined;
+  configureWebpackUtils: ConfigureWebpackUtils;
 }) {
-  const {plugins, siteConfig} = props;
+  const {plugins} = props;
   let {clientConfig: config} = await createStartClientConfig({
     props,
     minify,
     faster: props.siteConfig.future.experimental_faster,
     poll,
+    configureWebpackUtils,
   });
   config = executePluginsConfigureWebpack({
     plugins,
     config,
     isServer: false,
-    utils: await createConfigureWebpackUtils({siteConfig}),
+    configureWebpackUtils,
   });
   return config;
 }
@@ -157,10 +160,15 @@ export async function createWebpackDevServer({
   cliOptions: StartCLIOptions;
   openUrlContext: OpenUrlContext;
 }): Promise<WebpackDevServer> {
+  const configureWebpackUtils = await createConfigureWebpackUtils({
+    siteConfig: props.siteConfig,
+  });
+
   const config = await getStartClientConfig({
     props,
     minify: cliOptions.minify ?? true,
     poll: cliOptions.poll,
+    configureWebpackUtils,
   });
 
   const compiler = webpack(config);

packages/docusaurus/src/server/__tests__/__snapshots__/config.test.ts.snap

@@ -10,6 +10,7 @@ exports[`loadSiteConfig website with .cjs siteConfig 1`] = `
     "future": {
       "experimental_faster": {
         "mdxCrossCompilerCache": false,
+        "rspackBundler": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
       },
@@ -76,6 +77,7 @@ exports[`loadSiteConfig website with ts + js config 1`] = `
     "future": {
       "experimental_faster": {
         "mdxCrossCompilerCache": false,
+        "rspackBundler": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
       },
@@ -142,6 +144,7 @@ exports[`loadSiteConfig website with valid JS CJS config 1`] = `
     "future": {
       "experimental_faster": {
         "mdxCrossCompilerCache": false,
+        "rspackBundler": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
       },
@@ -208,6 +211,7 @@ exports[`loadSiteConfig website with valid JS ESM config 1`] = `
     "future": {
       "experimental_faster": {
         "mdxCrossCompilerCache": false,
+        "rspackBundler": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
       },
@@ -274,6 +278,7 @@ exports[`loadSiteConfig website with valid TypeScript CJS config 1`] = `
     "future": {
       "experimental_faster": {
         "mdxCrossCompilerCache": false,
+        "rspackBundler": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
       },
@@ -340,6 +345,7 @@ exports[`loadSiteConfig website with valid TypeScript ESM config 1`] = `
     "future": {
       "experimental_faster": {
         "mdxCrossCompilerCache": false,
+        "rspackBundler": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
       },
@@ -406,6 +412,7 @@ exports[`loadSiteConfig website with valid async config 1`] = `
     "future": {
       "experimental_faster": {
         "mdxCrossCompilerCache": false,
+        "rspackBundler": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
       },
@@ -474,6 +481,7 @@ exports[`loadSiteConfig website with valid async config creator function 1`] = `
     "future": {
       "experimental_faster": {
         "mdxCrossCompilerCache": false,
+        "rspackBundler": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
       },
@@ -542,6 +550,7 @@ exports[`loadSiteConfig website with valid config creator function 1`] = `
     "future": {
       "experimental_faster": {
         "mdxCrossCompilerCache": false,
+        "rspackBundler": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
       },
@@ -613,6 +622,7 @@ exports[`loadSiteConfig website with valid siteConfig 1`] = `
     "future": {
       "experimental_faster": {
         "mdxCrossCompilerCache": false,
+        "rspackBundler": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
       },

packages/docusaurus/src/server/__tests__/__snapshots__/site.test.ts.snap

@@ -80,6 +80,7 @@ exports[`load loads props for site with custom i18n path 1`] = `
     "future": {
       "experimental_faster": {
         "mdxCrossCompilerCache": false,
+        "rspackBundler": false,
         "swcJsLoader": false,
         "swcJsMinimizer": false,
       },