feat(core): Replace Webpack with Rspack - siteConfig.future.experimental_faster.rspackBundler

packages/docusaurus-bundler/src/currentBundler.ts

@@ -9,7 +9,7 @@ import webpack from 'webpack';
 import WebpackBar from 'webpackbar';
 import MiniCssExtractPlugin from 'mini-css-extract-plugin';
 import CopyWebpackPlugin from 'copy-webpack-plugin';
-import logger from '@docusaurus/logger';
+import {importRspack} from './importFaster';
 import type {CurrentBundler, DocusaurusConfig} from '@docusaurus/types';
 
 // We inject a site config slice because the Rspack flag might change place
@@ -32,10 +32,10 @@ export async function getCurrentBundler({
   siteConfig: SiteConfigSlice;
 }): Promise<CurrentBundler> {
   if (isRspack(siteConfig)) {
-    // TODO add support for Rspack
-    logger.error(
-      'Rspack bundler is not supported yet, will use Webpack instead',
-    );
+    return {
+      name: 'rspack',
+      instance: await importRspack(),
+    };
   }
   return {
     name: 'webpack',
@@ -49,7 +49,8 @@ export async function getCSSExtractPlugin({
   currentBundler: CurrentBundler;
 }): Promise<typeof MiniCssExtractPlugin> {
   if (currentBundler.name === 'rspack') {
-    throw new Error('Rspack bundler is not supported yet');
+    // @ts-expect-error: this exists only in Rspack
+    return currentBundler.instance.CssExtractRspackPlugin;
   }
   return MiniCssExtractPlugin;
 }
@@ -60,9 +61,9 @@ export async function getCopyPlugin({
   currentBundler: CurrentBundler;
 }): Promise<typeof CopyWebpackPlugin> {
   if (currentBundler.name === 'rspack') {
-    throw new Error('Rspack bundler is not supported yet');
+    // @ts-expect-error: this exists only in Rspack
+    return currentBundler.instance.CopyRspackPlugin;
   }
-  // https://github.com/webpack-contrib/copy-webpack-plugin
   return CopyWebpackPlugin;
 }
 

packages/docusaurus-bundler/src/importFaster.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import type webpack from 'webpack';
 import type {ConfigureWebpackUtils} from '@docusaurus/types';
 import type {
   MinimizerOptions as JsMinimizerOptions,
@@ -29,6 +30,11 @@ async function ensureFaster(): Promise<FasterModule> {
   }
 }
 
+export async function importRspack(): Promise<typeof webpack> {
+  const faster = await ensureFaster();
+  return faster.getRspack() as unknown as typeof webpack;
+}
+
 export async function importSwcJsLoaderFactory(): Promise<
   ConfigureWebpackUtils['getJSLoader']
 > {
@@ -50,6 +56,11 @@ export async function importSwcHtmlMinifier(): Promise<
   return faster.getSwcHtmlMinifier();
 }
 
+export async function importBrowserslistQueries(): Promise<string[]> {
+  const faster = await ensureFaster();
+  return faster.getBrowserslistQueries();
+}
+
 export async function importLightningCssMinimizerOptions(): Promise<
   CssMinimizerOptions<CustomOptions>
 > {

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

@@ -5,14 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {fromPartial} from '@total-typescript/shoehorn';
+import {fromPartial, type PartialDeep} from '@total-typescript/shoehorn';
 import {createJsLoaderFactory} from '../jsLoader';
 
 import type {RuleSetRule} from 'webpack';
 
 describe('createJsLoaderFactory', () => {
   function testJsLoaderFactory(
-    siteConfig?: Parameters<typeof createJsLoaderFactory>[0]['siteConfig'],
+    siteConfig?: PartialDeep<
+      Parameters<typeof createJsLoaderFactory>[0]['siteConfig']
+    >,
   ) {
     return createJsLoaderFactory({
       siteConfig: {
@@ -21,7 +23,12 @@ describe('createJsLoaderFactory', () => {
           jsLoader: 'babel',
           ...siteConfig?.webpack,
         },
-        future: fromPartial(siteConfig?.future),
+        future: fromPartial({
+          ...siteConfig?.future,
+          experimental_faster: fromPartial({
+            ...siteConfig?.future?.experimental_faster,
+          }),
+        }),
       },
     });
   }

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

@@ -7,6 +7,7 @@
 
 import {getBabelOptions} from '@docusaurus/babel';
 import {importSwcJsLoaderFactory} from '../importFaster';
+import {getCurrentBundler} from '../currentBundler';
 import type {ConfigureWebpackUtils, DocusaurusConfig} from '@docusaurus/types';
 
 const BabelJsLoaderFactory: ConfigureWebpackUtils['getJSLoader'] = ({
@@ -19,6 +20,25 @@ const BabelJsLoaderFactory: ConfigureWebpackUtils['getJSLoader'] = ({
   };
 };
 
+const RspackJsLoaderFactory: ConfigureWebpackUtils['getJSLoader'] = () => {
+  return {
+    loader: 'builtin:swc-loader',
+    options: {
+      jsc: {
+        parser: {
+          syntax: 'typescript',
+          tsx: true,
+        },
+        transform: {
+          react: {
+            runtime: 'automatic',
+          },
+        },
+      },
+    },
+  };
+};
+
 // Confusing: function that creates a function that creates actual js loaders
 // This is done on purpose because the js loader factory is a public API
 // It is injected in configureWebpack plugin lifecycle for plugin authors
@@ -27,11 +47,22 @@ export async function createJsLoaderFactory({
 }: {
   siteConfig: {
     webpack?: DocusaurusConfig['webpack'];
-    future?: {
+    future: {
       experimental_faster: DocusaurusConfig['future']['experimental_faster'];
     };
   };
 }): Promise<ConfigureWebpackUtils['getJSLoader']> {
+  const currentBundler = await getCurrentBundler({siteConfig});
+  const isSWCLoader = siteConfig.future.experimental_faster.swcJsLoader;
+
+  if (currentBundler.name === 'rspack') {
+    if (!isSWCLoader) {
+      throw new Error(
+        'When using Rspack bundler, it is required to enable swcJsLoader too',
+      );
+    }
+    return RspackJsLoaderFactory;
+  }
   const jsLoader = siteConfig.webpack?.jsLoader ?? 'babel';
   if (
     jsLoader instanceof Function &&

packages/docusaurus-bundler/src/minification.ts

@@ -10,6 +10,7 @@ import CssMinimizerPlugin from 'css-minimizer-webpack-plugin';
 import {
   importSwcJsMinimizerOptions,
   importLightningCssMinimizerOptions,
+  importBrowserslistQueries,
 } from './importFaster';
 import type {CustomOptions, CssNanoOptions} from 'css-minimizer-webpack-plugin';
 import type {WebpackPluginInstance} from 'webpack';
@@ -137,8 +138,23 @@ async function getWebpackMinimizers(
 async function getRspackMinimizers({
   currentBundler,
 }: MinimizersConfig): Promise<WebpackPluginInstance[]> {
-  console.log('currentBundler', currentBundler.name);
-  throw new Error('TODO Rspack minimizers not implemented yet');
+  const browserslistQueries = await importBrowserslistQueries();
+  return [
+    // @ts-expect-error: Rspack has this built-in
+    new currentBundler.instance.SwcJsMinimizerRspackPlugin(),
+    // @ts-expect-error: Rspack has this built-in
+    new currentBundler.instance.LightningCssMinimizerRspackPlugin({
+      minimizerOptions: {
+        ...(await importLightningCssMinimizerOptions()),
+        // Not sure why but Rspack takes browserslist queries directly
+        // While LightningCSS targets are normally not browserslist queries
+        // We have to override the option to avoid errors
+        // See https://rspack.dev/plugins/rspack/lightning-css-minimizer-rspack-plugin#minimizeroptions
+        // See https://lightningcss.dev/transpilation.html
+        targets: browserslistQueries,
+      },
+    }),
+  ];
 }
 
 export async function getMinimizers(

packages/docusaurus-faster/package.json

@@ -18,6 +18,7 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@rspack/core": "^1.0.8",
     "@swc/core": "^1.7.28",
     "@swc/html": "^1.7.28",
     "browserslist": "^4.24.0",

packages/docusaurus-faster/src/index.ts

@@ -5,12 +5,17 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import Rspack from '@rspack/core';
 import * as lightningcss from 'lightningcss';
 import browserslist from 'browserslist';
 import {minify as swcHtmlMinifier} from '@swc/html';
 import type {RuleSetRule} from 'webpack';
 import type {JsMinifyOptions} from '@swc/core';
 
+export function getRspack(): typeof Rspack {
+  return Rspack;
+}
+
 export function getSwcHtmlMinifier(): typeof swcHtmlMinifier {
   return swcHtmlMinifier;
 }
@@ -63,6 +68,15 @@ export function getSwcJsMinimizerOptions(): JsMinifyOptions {
   };
 }
 
+// We need this because of Rspack built-in LightningCSS integration
+// See https://github.com/orgs/browserslist/discussions/846
+export function getBrowserslistQueries(): string[] {
+  const queries = browserslist.loadConfig({path: process.cwd()}) ?? [
+    ...browserslist.defaults,
+  ];
+  return queries;
+}
+
 // LightningCSS doesn't expose any type for css-minimizer-webpack-plugin setup
 // So we derive it ourselves
 // see https://lightningcss.dev/docs.html#with-webpack

packages/docusaurus-theme-classic/package.json

@@ -21,6 +21,7 @@
   },
   "dependencies": {
     "@docusaurus/core": "3.5.2",
+    "@docusaurus/logger": "3.5.2",
     "@docusaurus/mdx-loader": "3.5.2",
     "@docusaurus/module-type-aliases": "3.5.2",
     "@docusaurus/plugin-content-blog": "3.5.2",

packages/docusaurus/src/client/docusaurus.ts

@@ -17,7 +17,7 @@ const loaded = new Set<string>();
 
 declare global {
   // eslint-disable-next-line camelcase, no-underscore-dangle
-  const __webpack_require__: {gca: (name: string) => string};
+  const __webpack_require__: {gca?: (name: string) => string};
   interface Navigator {
     connection?: {effectiveType: string; saveData: boolean};
   }
@@ -65,17 +65,22 @@ const prefetch: Docusaurus['prefetch'] = (
   // Prefetch all webpack chunk assets file needed.
   return Promise.all(
     chunkNamesNeeded.map((chunkName) => {
+      // TODO
+      if (!__webpack_require__.gca) {
+        console.warn('Rspack bug to fix: unable to prefetch');
+        return Promise.resolve();
+      }
       // "__webpack_require__.gca" is injected by ChunkAssetPlugin. Pass it
       // the name of the chunk you want to load and it will return its URL.
       // eslint-disable-next-line camelcase
       const chunkAsset = __webpack_require__.gca(chunkName);
-
       // In some cases, webpack might decide to optimize further, leading to
       // the chunk assets being merged to another chunk. In this case, we can
       // safely filter it out and don't need to load it.
       if (chunkAsset && !chunkAsset.includes('undefined')) {
         return prefetchHelper(chunkAsset);
       }
+
       return Promise.resolve();
     }),
   );

packages/docusaurus/src/commands/build.ts

@@ -189,17 +189,14 @@ async function buildLocale({
     );
 
   // Run webpack to build JS bundle (client) and static html files (server).
-  await PerfLogger.async(
-    `Bundling with ${configureWebpackUtils.currentBundler.name}`,
-    () => {
-      return compile({
-        configs:
-          // For hash router we don't do SSG and can skip the server bundle
-          router === 'hash' ? [clientConfig] : [clientConfig, serverConfig],
-        currentBundler: configureWebpackUtils.currentBundler,
-      });
-    },
-  );
+  await PerfLogger.async(`Bundling with ${props.currentBundler.name}`, () => {
+    return compile({
+      configs:
+        // For hash router we don't do SSG and can skip the server bundle
+        router === 'hash' ? [clientConfig] : [clientConfig, serverConfig],
+      currentBundler: configureWebpackUtils.currentBundler,
+    });
+  });
 
   const {collectedData} = await PerfLogger.async('SSG', () =>
     executeSSG({

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

@@ -7,7 +7,6 @@
 
 import path from 'path';
 import merge from 'webpack-merge';
-import webpack from 'webpack';
 import {formatStatsErrorMessage, printStatsWarnings} from '@docusaurus/bundler';
 import logger from '@docusaurus/logger';
 import WebpackDevServer from 'webpack-dev-server';
@@ -168,7 +167,7 @@ export async function createWebpackDevServer({
     configureWebpackUtils,
   });
 
-  const compiler = webpack(config);
+  const compiler = props.currentBundler.instance(config);
   registerWebpackE2ETestHook(compiler);
 
   const defaultDevServerConfig = await createDevServerConfig({

packages/docusaurus/src/webpack/base.ts

@@ -98,10 +98,14 @@ export async function createBaseConfig({
     currentBundler: props.currentBundler,
   });
 
-  return {
-    mode,
-    name,
-    cache: {
+  function getCache(): Configuration['cache'] {
+    if (props.currentBundler.name === 'rspack') {
+      // TODO Rspack only supports memory cache (as of Sept 2024)
+      // TODO re-enable file persistent cache one Rspack supports it
+      //  See also https://rspack.dev/config/cache#cache
+      return undefined;
+    }
+    return {
       type: 'filesystem',
       // Can we share the same cache across locales?
       // Exploring that question at https://github.com/webpack/webpack/issues/13034
@@ -127,7 +131,13 @@ export async function createBaseConfig({
           siteConfigPath,
         ],
       },
-    },
+    };
+  }
+
+  return {
+    mode,
+    name,
+    cache: getCache(),
     output: {
       pathinfo: false,
       path: outDir,
@@ -145,7 +155,6 @@ export async function createBaseConfig({
     },
     devtool: isProd ? undefined : 'eval-cheap-module-source-map',
     resolve: {
-      unsafeCache: false, // Not enabled, does not seem to improve perf much
       extensions: ['.wasm', '.mjs', '.js', '.jsx', '.ts', '.tsx', '.json'],
       symlinks: true, // See https://github.com/facebook/docusaurus/issues/3272
       roots: [

packages/docusaurus/src/webpack/client.ts

@@ -45,7 +45,7 @@ async function createBaseClientConfig({
   });
 
   const ProgressBarPlugin = await getProgressBarPlugin({
-    currentBundler: configureWebpackUtils.currentBundler,
+    currentBundler: props.currentBundler,
   });
 
   return merge(baseConfig, {

packages/docusaurus/src/webpack/plugins/ChunkAssetPlugin.ts

@@ -68,6 +68,8 @@ export default class ChunkAssetPlugin {
 }
 
 // Inspired by https://github.com/webpack/webpack/blob/v5.94.0/lib/runtime/CompatRuntimeModule.js
+// See also https://rspack.dev/api/javascript-api/compilation#addruntimemodule
+// See also https://rspack.dev/api/plugin-api/compilation-hooks#additionaltreeruntimerequirements
 class ChunkAssetRuntimeModule extends webpack.RuntimeModule {
   constructor() {
     super('ChunkAssetRuntimeModule', webpack.RuntimeModule.STAGE_ATTACH);

website/docusaurus.config.ts

@@ -24,6 +24,7 @@ import ConfigLocalized from './docusaurus.config.localized.json';
 
 import PrismLight from './src/utils/prismLight';
 import PrismDark from './src/utils/prismDark';
+
 import type {Config, DocusaurusConfig} from '@docusaurus/types';
 
 import type * as Preset from '@docusaurus/preset-classic';