feat(core): faster CSS minimizer - siteConfig.future.experimental_faster.lightningCssMinimizer

packages/docusaurus-bundler/src/importFaster.ts

@@ -6,7 +6,11 @@
  */
 
 import type {ConfigureWebpackUtils} from '@docusaurus/types';
-import type {MinimizerOptions, CustomOptions} from 'terser-webpack-plugin';
+import type {
+  MinimizerOptions as JsMinimizerOptions,
+  CustomOptions,
+} from 'terser-webpack-plugin';
+import type {MinimizerOptions as CssMinimizerOptions} from 'css-minimizer-webpack-plugin';
 
 async function importFaster() {
   return import('@docusaurus/faster');
@@ -30,9 +34,16 @@ export async function importSwcJsLoaderFactory(): Promise<
   return faster.getSwcJsLoaderFactory;
 }
 
-export async function importSwcJsMinifierOptions(): Promise<
-  MinimizerOptions<CustomOptions>
+export async function importSwcJsMinimizerOptions(): Promise<
+  JsMinimizerOptions<CustomOptions>
 > {
   const faster = await ensureFaster();
-  return faster.getSwcJsMinifierOptions() as MinimizerOptions<CustomOptions>;
+  return faster.getSwcJsMinimizerOptions() as JsMinimizerOptions<CustomOptions>;
+}
+
+export async function importLightningCssMinimizerOptions(): Promise<
+  CssMinimizerOptions<CustomOptions>
+> {
+  const faster = await ensureFaster();
+  return faster.getLightningCssMinimizerOptions() as CssMinimizerOptions<CustomOptions>;
 }

packages/docusaurus-bundler/src/minification.ts

@@ -7,13 +7,16 @@
 
 import TerserPlugin from 'terser-webpack-plugin';
 import CssMinimizerPlugin from 'css-minimizer-webpack-plugin';
-import {importSwcJsMinifierOptions} from './importFaster';
+import {
+  importSwcJsMinimizerOptions,
+  importLightningCssMinimizerOptions,
+} from './importFaster';
 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'>;
+  faster: Pick<FasterConfig, 'swcJsMinimizer' | 'lightningCssMinimizer'>;
   currentBundler: CurrentBundler;
 };
 
@@ -31,9 +34,11 @@ function getTerserParallel() {
   return terserParallel;
 }
 
-async function getJsMinimizer({faster}: MinimizersConfig) {
+async function getJsMinimizer({
+  faster,
+}: MinimizersConfig): Promise<WebpackPluginInstance> {
   if (faster.swcJsMinimizer) {
-    const terserOptions = await importSwcJsMinifierOptions();
+    const terserOptions = await importSwcJsMinimizerOptions();
     return new TerserPlugin({
       parallel: getTerserParallel(),
       minify: TerserPlugin.swcMinify,
@@ -69,7 +74,21 @@ async function getJsMinimizer({faster}: MinimizersConfig) {
   });
 }
 
-function getAdvancedCssMinifier() {
+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]>({
@@ -101,21 +120,18 @@ function getAdvancedCssMinifier() {
   });
 }
 
-function getCssMinimizer(): WebpackPluginInstance {
-  // This is an historical env variable to opt-out of the advanced minifier
-  // 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();
-  } else {
-    return getAdvancedCssMinifier();
-  }
+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()]);
+  return Promise.all([getJsMinimizer(params), getCssMinimizer(params)]);
 }
 
 async function getRspackMinimizers({

packages/docusaurus-faster/package.json

@@ -18,9 +18,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "webpack": "^5.88.1",
     "@swc/core": "^1.7.14",
-    "swc-loader": "^0.2.6"
+    "browserslist": "^4.24.0",
+    "lightningcss": "^1.27.0",
+    "swc-loader": "^0.2.6",
+    "webpack": "^5.88.1"
   },
   "engines": {
     "node": ">=18.0"

packages/docusaurus-faster/src/index.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import * as lightningcss from 'lightningcss';
+import browserslist from 'browserslist';
 import type {RuleSetRule} from 'webpack';
 import type {JsMinifyOptions} from '@swc/core';
 
@@ -39,7 +41,7 @@ export function getSwcJsLoaderFactory({
 // They should rather be kept in sync for now to avoid any unexpected behavior
 // The goal of faster minifier is not to fine-tune options but only to be faster
 // See core minification.ts
-export function getSwcJsMinifierOptions(): JsMinifyOptions {
+export function getSwcJsMinimizerOptions(): JsMinifyOptions {
   return {
     ecma: 2020,
     compress: {
@@ -55,3 +57,16 @@ export function getSwcJsMinifierOptions(): JsMinifyOptions {
     },
   };
 }
+
+// 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
+type LightningCssMinimizerOptions = Omit<
+  lightningcss.TransformOptions<never>,
+  'filename' | 'code'
+>;
+
+export function getLightningCssMinimizerOptions(): LightningCssMinimizerOptions {
+  const queries = browserslist();
+  return {targets: lightningcss.browserslistToTargets(queries)};
+}

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

@@ -126,6 +126,7 @@ export type StorageConfig = {
 export type FasterConfig = {
   swcJsLoader: boolean;
   swcJsMinimizer: boolean;
+  lightningCssMinimizer: boolean;
   mdxCrossCompilerCache: boolean;
   rspackBundler: boolean;
 };

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

@@ -9,6 +9,7 @@ exports[`loadSiteConfig website with .cjs siteConfig 1`] = `
     "customFields": {},
     "future": {
       "experimental_faster": {
+        "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
         "swcJsLoader": false,
@@ -76,6 +77,7 @@ exports[`loadSiteConfig website with ts + js config 1`] = `
     "customFields": {},
     "future": {
       "experimental_faster": {
+        "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
         "swcJsLoader": false,
@@ -143,6 +145,7 @@ exports[`loadSiteConfig website with valid JS CJS config 1`] = `
     "customFields": {},
     "future": {
       "experimental_faster": {
+        "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
         "swcJsLoader": false,
@@ -210,6 +213,7 @@ exports[`loadSiteConfig website with valid JS ESM config 1`] = `
     "customFields": {},
     "future": {
       "experimental_faster": {
+        "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
         "swcJsLoader": false,
@@ -277,6 +281,7 @@ exports[`loadSiteConfig website with valid TypeScript CJS config 1`] = `
     "customFields": {},
     "future": {
       "experimental_faster": {
+        "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
         "swcJsLoader": false,
@@ -344,6 +349,7 @@ exports[`loadSiteConfig website with valid TypeScript ESM config 1`] = `
     "customFields": {},
     "future": {
       "experimental_faster": {
+        "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
         "swcJsLoader": false,
@@ -411,6 +417,7 @@ exports[`loadSiteConfig website with valid async config 1`] = `
     "customFields": {},
     "future": {
       "experimental_faster": {
+        "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
         "swcJsLoader": false,
@@ -480,6 +487,7 @@ exports[`loadSiteConfig website with valid async config creator function 1`] = `
     "customFields": {},
     "future": {
       "experimental_faster": {
+        "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
         "swcJsLoader": false,
@@ -549,6 +557,7 @@ exports[`loadSiteConfig website with valid config creator function 1`] = `
     "customFields": {},
     "future": {
       "experimental_faster": {
+        "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
         "swcJsLoader": false,
@@ -621,6 +630,7 @@ exports[`loadSiteConfig website with valid siteConfig 1`] = `
     "favicon": "img/docusaurus.ico",
     "future": {
       "experimental_faster": {
+        "lightningCssMinimizer": false,
         "mdxCrossCompilerCache": false,
         "rspackBundler": false,
         "swcJsLoader": false,

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

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

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

@@ -48,6 +48,7 @@ describe('normalizeConfig', () => {
         experimental_faster: {
           swcJsLoader: true,
           swcJsMinimizer: true,
+          lightningCssMinimizer: true,
           mdxCrossCompilerCache: true,
           rspackBundler: true,
         },
@@ -745,6 +746,7 @@ describe('future', () => {
       experimental_faster: {
         swcJsLoader: true,
         swcJsMinimizer: true,
+        lightningCssMinimizer: true,
         mdxCrossCompilerCache: true,
         rspackBundler: true,
       },
@@ -1096,6 +1098,7 @@ describe('future', () => {
       const faster: FasterConfig = {
         swcJsLoader: true,
         swcJsMinimizer: true,
+        lightningCssMinimizer: true,
         mdxCrossCompilerCache: true,
         rspackBundler: true,
       };
@@ -1281,6 +1284,77 @@ describe('future', () => {
       });
     });
 
+    describe('lightningCssMinimizer', () => {
+      it('accepts - undefined', () => {
+        const faster: Partial<FasterConfig> = {
+          lightningCssMinimizer: undefined,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toEqual(fasterContaining({lightningCssMinimizer: false}));
+      });
+
+      it('accepts - true', () => {
+        const faster: Partial<FasterConfig> = {
+          lightningCssMinimizer: true,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toEqual(fasterContaining({lightningCssMinimizer: true}));
+      });
+
+      it('accepts - false', () => {
+        const faster: Partial<FasterConfig> = {
+          lightningCssMinimizer: false,
+        };
+        expect(
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toEqual(fasterContaining({lightningCssMinimizer: false}));
+      });
+
+      it('rejects - null', () => {
+        // @ts-expect-error: invalid
+        const faster: Partial<FasterConfig> = {lightningCssMinimizer: 42};
+        expect(() =>
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toThrowErrorMatchingInlineSnapshot(`
+          ""future.experimental_faster.lightningCssMinimizer" must be a boolean
+          "
+        `);
+      });
+
+      it('rejects - number', () => {
+        // @ts-expect-error: invalid
+        const faster: Partial<FasterConfig> = {lightningCssMinimizer: 42};
+        expect(() =>
+          normalizeConfig({
+            future: {
+              experimental_faster: faster,
+            },
+          }),
+        ).toThrowErrorMatchingInlineSnapshot(`
+          ""future.experimental_faster.lightningCssMinimizer" must be a boolean
+          "
+        `);
+      });
+    });
+
     describe('mdxCrossCompilerCache', () => {
       it('accepts - undefined', () => {
         const faster: Partial<FasterConfig> = {

packages/docusaurus/src/server/configValidation.ts

@@ -44,6 +44,7 @@ export const DEFAULT_STORAGE_CONFIG: StorageConfig = {
 export const DEFAULT_FASTER_CONFIG: FasterConfig = {
   swcJsLoader: false,
   swcJsMinimizer: false,
+  lightningCssMinimizer: false,
   mdxCrossCompilerCache: false,
   rspackBundler: false,
 };
@@ -52,6 +53,7 @@ export const DEFAULT_FASTER_CONFIG: FasterConfig = {
 export const DEFAULT_FASTER_CONFIG_TRUE: FasterConfig = {
   swcJsLoader: true,
   swcJsMinimizer: true,
+  lightningCssMinimizer: true,
   mdxCrossCompilerCache: true,
   rspackBundler: true,
 };
@@ -221,6 +223,9 @@ const FASTER_CONFIG_SCHEMA = Joi.alternatives()
       swcJsMinimizer: Joi.boolean().default(
         DEFAULT_FASTER_CONFIG.swcJsMinimizer,
       ),
+      lightningCssMinimizer: Joi.boolean().default(
+        DEFAULT_FASTER_CONFIG.lightningCssMinimizer,
+      ),
       mdxCrossCompilerCache: Joi.boolean().default(
         DEFAULT_FASTER_CONFIG.mdxCrossCompilerCache,
       ),

project-words.txt

@@ -164,6 +164,7 @@ lastmod
 Lastmod
 lifecycles
 Lifecycles
+lightningcss
 linkify
 Linkify
 Localizable