@docusaurus/bundler 3.5.2 → 3.6.0

package/src/index.ts

@@ -5,85 +5,20 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-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 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'
-    >;
-  };
-};
-
-function isRspack(siteConfig: SiteConfigSlice): boolean {
-  return siteConfig.future.experimental_faster.rspackBundler;
-}
-
-export async function getCurrentBundler({
-  siteConfig,
-}: {
-  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: 'webpack',
-    instance: webpack,
-  };
-}
-
-export async function getCSSExtractPlugin({
-  currentBundler,
-}: {
-  currentBundler: CurrentBundler;
-}): Promise<typeof MiniCssExtractPlugin> {
-  if (currentBundler.name === 'rspack') {
-    throw new Error('Rspack bundler is not supported yet');
-  }
-  return MiniCssExtractPlugin;
-}
-
-export async function getCopyPlugin({
-  currentBundler,
-}: {
-  currentBundler: CurrentBundler;
-}): Promise<typeof CopyWebpackPlugin> {
-  if (currentBundler.name === 'rspack') {
-    throw new Error('Rspack bundler is not supported yet');
-  }
-  // https://github.com/webpack-contrib/copy-webpack-plugin
-  return CopyWebpackPlugin;
-}
-
-export async function getProgressBarPlugin({
-  currentBundler,
-}: {
-  currentBundler: CurrentBundler;
-}): Promise<typeof WebpackBar> {
-  if (currentBundler.name === 'rspack') {
-    class CustomRspackProgressPlugin extends currentBundler.instance
-      .ProgressPlugin {
-      constructor({name}: {name: string}) {
-        // TODO add support for color
-        // Unfortunately the rspack.ProgressPlugin does not have a name option
-        // See https://rspack.dev/plugins/webpack/progress-plugin
-        // @ts-expect-error: adapt Rspack ProgressPlugin constructor
-        super({prefix: name});
-      }
-    }
-    return CustomRspackProgressPlugin as typeof WebpackBar;
-  }
-
-  return WebpackBar;
-}
+export {printStatsWarnings, formatStatsErrorMessage, compile} from './compiler';
+
+export {
+  getCurrentBundler,
+  getCSSExtractPlugin,
+  getCopyPlugin,
+  getProgressBarPlugin,
+} from './currentBundler';
+
+export {getMinimizers} from './minification';
+export {
+  getHtmlMinifier,
+  type HtmlMinifier,
+  type HtmlMinifierType,
+} from './minifyHtml';
+export {createJsLoaderFactory} from './loaders/jsLoader';
+export {createStyleLoadersFactory} from './loaders/styleLoader';

package/src/loaders/jsLoader.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 {getBabelOptions} from '@docusaurus/babel';
+import {importSwcLoader, importGetSwcLoaderOptions} from '../importFaster';
+import {getCurrentBundler} from '../currentBundler';
+import type {ConfigureWebpackUtils, DocusaurusConfig} from '@docusaurus/types';
+
+const BabelJsLoaderFactory: ConfigureWebpackUtils['getJSLoader'] = ({
+  isServer,
+  babelOptions,
+}) => {
+  return {
+    loader: require.resolve('babel-loader'),
+    options: getBabelOptions({isServer, babelOptions}),
+  };
+};
+
+async function createSwcJsLoaderFactory(): Promise<
+  ConfigureWebpackUtils['getJSLoader']
+> {
+  const loader = await importSwcLoader();
+  const getOptions = await importGetSwcLoaderOptions();
+  return ({isServer}) => {
+    return {
+      loader,
+      options: getOptions({isServer}),
+    };
+  };
+}
+
+// Same as swcLoader, except we use the built-in SWC loader
+async function createRspackSwcJsLoaderFactory(): Promise<
+  ConfigureWebpackUtils['getJSLoader']
+> {
+  const loader = 'builtin:swc-loader';
+  const getOptions = await importGetSwcLoaderOptions();
+  return ({isServer}) => {
+    return {
+      loader,
+      options: getOptions({isServer}),
+    };
+  };
+}
+
+// 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
+export async function createJsLoaderFactory({
+  siteConfig,
+}: {
+  siteConfig: {
+    webpack?: DocusaurusConfig['webpack'];
+    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') {
+    return isSWCLoader
+      ? createRspackSwcJsLoaderFactory()
+      : BabelJsLoaderFactory;
+  }
+  const jsLoader = siteConfig.webpack?.jsLoader ?? 'babel';
+  if (
+    jsLoader instanceof Function &&
+    siteConfig.future?.experimental_faster.swcJsLoader
+  ) {
+    throw new Error(
+      "You can't use a custom webpack.jsLoader and experimental_faster.swcJsLoader at the same time",
+    );
+  }
+  if (jsLoader instanceof Function) {
+    return ({isServer}) => jsLoader(isServer);
+  }
+  if (siteConfig.future?.experimental_faster.swcJsLoader) {
+    return createSwcJsLoaderFactory();
+  }
+  if (jsLoader === 'babel') {
+    return BabelJsLoaderFactory;
+  }
+  throw new Error(`Docusaurus bug: unexpected jsLoader value${jsLoader}`);
+}

package/src/loaders/styleLoader.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 {getCSSExtractPlugin} from '../currentBundler';
+import type {ConfigureWebpackUtils, CurrentBundler} from '@docusaurus/types';
+
+export async function createStyleLoadersFactory({
+  currentBundler,
+}: {
+  currentBundler: CurrentBundler;
+}): Promise<ConfigureWebpackUtils['getStyleLoaders']> {
+  const CssExtractPlugin = await getCSSExtractPlugin({currentBundler});
+
+  return function getStyleLoaders(
+    isServer: boolean,
+    cssOptionsArg: {
+      [key: string]: unknown;
+    } = {},
+  ) {
+    const cssOptions: {[key: string]: unknown} = {
+      // TODO turn esModule on later, see https://github.com/facebook/docusaurus/pull/6424
+      esModule: false,
+      ...cssOptionsArg,
+    };
+
+    // On the server we don't really need to extract/emit CSS
+    // We only need to transform CSS module imports to a styles object
+    if (isServer) {
+      return cssOptions.modules
+        ? [
+            {
+              loader: require.resolve('css-loader'),
+              options: cssOptions,
+            },
+          ]
+        : // Ignore regular CSS files
+          [{loader: require.resolve('null-loader')}];
+    }
+
+    return [
+      {
+        loader: CssExtractPlugin.loader,
+        options: {
+          esModule: true,
+        },
+      },
+      {
+        loader: require.resolve('css-loader'),
+        options: cssOptions,
+      },
+
+      // TODO apart for configurePostCss(), do we really need this loader?
+      // Note: using postcss here looks inefficient/duplicate
+      // But in practice, it's not a big deal because css-loader also uses postcss
+      // and is able to reuse the parsed AST from postcss-loader
+      // See https://github.com/webpack-contrib/css-loader/blob/master/src/index.js#L159
+      {
+        // Options for PostCSS as we reference these options twice
+        // Adds vendor prefixing based on your specified browser support in
+        // package.json
+        loader: require.resolve('postcss-loader'),
+        options: {
+          postcssOptions: {
+            // Necessary for external CSS imports to work
+            // https://github.com/facebook/create-react-app/issues/2677
+            ident: 'postcss',
+            plugins: [
+              // eslint-disable-next-line global-require
+              require('autoprefixer'),
+            ],
+          },
+        },
+      },
+    ];
+  };
+}

package/src/minification.ts

@@ -0,0 +1,176 @@
+/**
+ * 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 TerserPlugin from 'terser-webpack-plugin';
+import CssMinimizerPlugin from 'css-minimizer-webpack-plugin';
+import {
+  importSwcJsMinimizerOptions,
+  importLightningCssMinimizerOptions,
+  importGetBrowserslistQueries,
+} from './importFaster';
+import {getCurrentBundlerAsRspack} from './currentBundler';
+import type {CustomOptions, CssNanoOptions} from 'css-minimizer-webpack-plugin';
+import type {WebpackPluginInstance} from 'webpack';
+import type {CurrentBundler, FasterConfig} from '@docusaurus/types';
+
+export type MinimizersConfig = {
+  faster: Pick<FasterConfig, 'swcJsMinimizer' | 'lightningCssMinimizer'>;
+  currentBundler: CurrentBundler;
+};
+
+// See https://github.com/webpack-contrib/terser-webpack-plugin#parallel
+function getTerserParallel() {
+  let terserParallel: boolean | number = true;
+  if (process.env.TERSER_PARALLEL === 'false') {
+    terserParallel = false;
+  } else if (
+    process.env.TERSER_PARALLEL &&
+    parseInt(process.env.TERSER_PARALLEL, 10) > 0
+  ) {
+    terserParallel = parseInt(process.env.TERSER_PARALLEL, 10);
+  }
+  return terserParallel;
+}
+
+async function getJsMinimizer({
+  faster,
+}: MinimizersConfig): Promise<WebpackPluginInstance> {
+  if (faster.swcJsMinimizer) {
+    const terserOptions = await importSwcJsMinimizerOptions();
+    return new TerserPlugin({
+      parallel: getTerserParallel(),
+      minify: TerserPlugin.swcMinify,
+      terserOptions,
+    });
+  }
+
+  return new TerserPlugin({
+    parallel: getTerserParallel(),
+    // See https://terser.org/docs/options/
+    terserOptions: {
+      parse: {
+        // We want uglify-js to parse ecma 8 code. However, we don't want it
+        // to apply any minification steps that turns valid ecma 5 code
+        // into invalid ecma 5 code. This is why the 'compress' and 'output'
+        // sections only apply transformations that are ecma 5 safe
+        // https://github.com/facebook/create-react-app/pull/4234
+        ecma: 2020,
+      },
+      compress: {
+        ecma: 5,
+      },
+      mangle: {
+        safari10: true,
+      },
+      output: {
+        ecma: 5,
+        comments: false,
+        // Turned on because emoji and regex is not minified properly using
+        // default. See https://github.com/facebook/create-react-app/issues/2488
+        ascii_only: true,
+      },
+    },
+  });
+}
+
+async function getLightningCssMinimizer(): Promise<WebpackPluginInstance> {
+  return new CssMinimizerPlugin({
+    minify: CssMinimizerPlugin.lightningCssMinify,
+    minimizerOptions: await importLightningCssMinimizerOptions(),
+  });
+}
+
+async function getCssNanoMinimizer(): Promise<WebpackPluginInstance> {
+  // This is an historical env variable to opt-out of the advanced minimizer
+  // Sometimes there's a bug in it and people are happy to disable it
+  const useSimpleCssMinifier = process.env.USE_SIMPLE_CSS_MINIFIER === 'true';
+  if (useSimpleCssMinifier) {
+    return new CssMinimizerPlugin();
+  }
+
+  // Using the array syntax to add 2 minimizers
+  // see https://github.com/webpack-contrib/css-minimizer-webpack-plugin#array
+  return new CssMinimizerPlugin<[CssNanoOptions, CustomOptions]>({
+    minimizerOptions: [
+      // CssNano options
+      {
+        preset: require.resolve('@docusaurus/cssnano-preset'),
+      },
+      // CleanCss options
+      {
+        inline: false,
+        level: {
+          1: {
+            all: false,
+            removeWhitespace: true,
+          },
+          2: {
+            all: true,
+            restructureRules: true,
+            removeUnusedAtRules: false,
+          },
+        },
+      },
+    ],
+    minify: [
+      CssMinimizerPlugin.cssnanoMinify,
+      CssMinimizerPlugin.cleanCssMinify,
+    ],
+  });
+}
+
+async function getCssMinimizer(
+  params: MinimizersConfig,
+): Promise<WebpackPluginInstance> {
+  return params.faster.lightningCssMinimizer
+    ? getLightningCssMinimizer()
+    : getCssNanoMinimizer();
+}
+
+async function getWebpackMinimizers(
+  params: MinimizersConfig,
+): Promise<WebpackPluginInstance[]> {
+  return Promise.all([getJsMinimizer(params), getCssMinimizer(params)]);
+}
+
+async function getRspackMinimizers({
+  currentBundler,
+}: MinimizersConfig): Promise<WebpackPluginInstance[]> {
+  const rspack = getCurrentBundlerAsRspack({currentBundler});
+  const getBrowserslistQueries = await importGetBrowserslistQueries();
+  const browserslistQueries = getBrowserslistQueries({isServer: false});
+  const swcJsMinimizerOptions = await importSwcJsMinimizerOptions();
+  return [
+    // See https://rspack.dev/plugins/rspack/swc-js-minimizer-rspack-plugin
+    // See https://swc.rs/docs/configuration/minification
+    new rspack.SwcJsMinimizerRspackPlugin({
+      minimizerOptions: {
+        minify: true,
+        ...swcJsMinimizerOptions,
+      },
+    }),
+    new rspack.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,
+      },
+    }),
+  ] as unknown as WebpackPluginInstance[];
+}
+
+export async function getMinimizers(
+  params: MinimizersConfig,
+): Promise<WebpackPluginInstance[]> {
+  return params.currentBundler.name === 'rspack'
+    ? getRspackMinimizers(params)
+    : getWebpackMinimizers(params);
+}

package/src/minifyHtml.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 {minify as terserHtmlMinifier} from 'html-minifier-terser';
+import {importSwcHtmlMinifier} from './importFaster';
+
+// Historical env variable
+const SkipHtmlMinification = process.env.SKIP_HTML_MINIFICATION === 'true';
+
+export type HtmlMinifierType = 'swc' | 'terser';
+
+export type HtmlMinifierResult = {
+  code: string;
+  warnings: string[];
+};
+
+export type HtmlMinifier = {
+  minify: (html: string) => Promise<HtmlMinifierResult>;
+};
+
+const NoopMinifier: HtmlMinifier = {
+  minify: async (html: string) => ({code: html, warnings: []}),
+};
+
+export async function getHtmlMinifier({
+  type,
+}: {
+  type: HtmlMinifierType;
+}): Promise<HtmlMinifier> {
+  if (SkipHtmlMinification) {
+    return NoopMinifier;
+  }
+  if (type === 'swc') {
+    return getSwcMinifier();
+  } else {
+    return getTerserMinifier();
+  }
+}
+
+// Minify html with https://github.com/DanielRuf/html-minifier-terser
+async function getTerserMinifier(): Promise<HtmlMinifier> {
+  return {
+    minify: async function minifyHtmlWithTerser(html) {
+      try {
+        const code = await terserHtmlMinifier(html, {
+          removeComments: false,
+          removeRedundantAttributes: true,
+          removeEmptyAttributes: true,
+          removeScriptTypeAttributes: true,
+          removeStyleLinkTypeAttributes: true,
+          useShortDoctype: true,
+          minifyJS: true,
+        });
+        return {code, warnings: []};
+      } catch (err) {
+        throw new Error(`HTML minification failed (Terser)`, {
+          cause: err as Error,
+        });
+      }
+    },
+  };
+}
+
+// Minify html with @swc/html
+// Not well-documented but fast!
+// See https://github.com/swc-project/swc/discussions/9616
+async function getSwcMinifier(): Promise<HtmlMinifier> {
+  const swcHtmlMinifier = await importSwcHtmlMinifier();
+  return {
+    minify: async function minifyHtmlWithSwc(html) {
+      try {
+        const result = await swcHtmlMinifier(Buffer.from(html), {
+          // Removing comments can lead to React hydration errors
+          // See https://x.com/sebastienlorber/status/1841966927440478577
+          removeComments: false,
+          // TODO maybe it's fine to only keep <!-- --> React comments?
+          preserveComments: [],
+
+          // Sorting these attributes (class) can lead to React hydration errors
+          sortSpaceSeparatedAttributeValues: false,
+          sortAttributes: false,
+
+          removeRedundantAttributes: 'all',
+          removeEmptyAttributes: true,
+          minifyJs: true,
+          minifyJson: true,
+          minifyCss: true,
+        });
+
+        const warnings = (result.errors ?? []).map((diagnostic) => {
+          return `[HTML minifier diagnostic - ${diagnostic.level}] ${
+            diagnostic.message
+          } - ${JSON.stringify(diagnostic.span)}`;
+        });
+
+        return {
+          code: result.code,
+          warnings,
+        };
+      } catch (err) {
+        throw new Error(`HTML minification failed (SWC)`, {
+          cause: err as Error,
+        });
+      }
+    },
+  };
+}