rsbuild-plugin-css-optimizer

An Rsbuild plugin to customize CSS minification, allowing you to choose between cssnano (JavaScript-based) or Lightning CSS (Rust-based) for high-performance CSS compression.

rsbuild-plugin-css-optimizer internally integrates css-minimizer-webpack-plugin to optimize CSS assets in production builds.

Features

• Flexible Minifier Choice: Switch between cssnano for extensive optimizations or Lightning CSS for 5-10x faster minification.
• Performance: Leverage Lightning CSS’s Rust-based engine for parallel processing and native performance.
• Type Safety: TypeScript types ensure correct configuration for each minifier.
• Seamless Rsbuild Integration: Automatically applies minification in production builds when minify.css is enabled.
• Customizable Options: Fine-tune cssnano and Lightning CSS settings for browser targeting, CSS features, and more.

Installation

Install the plugin and its dependency:

npm add rsbuild-plugin-css-optimizer -D

Usage

Add the pluginCssMinimizer to your Rsbuild configuration in rsbuild.config.ts. The plugin enables CSS minification in production builds when output.minify.css is true.

Basic Example (Lightning CSS)

// rsbuild.config.ts
import { pluginCssMinimizer } from "rsbuild-plugin-css-optimizer";

export default {
  plugins: [
    pluginCssMinimizer({
      minifier: "lightningcss",
      lightningCssOptions: {
        minimizerOptions: {
          targets: ["> 0.25%", "not dead"],
        },
      },
    }),
  ],
};

Basic Example (cssnano)

// rsbuild.config.ts
import { pluginCssMinimizer } from "rsbuild-plugin-css-optimizer";

export default {
  plugins: [
    pluginCssMinimizer(), // Uses cssnano by default
  ],
};

Options

The plugin accepts a PluginCssMinimizerOptions object with the following properties:

minifier

• Type: 'cssnano' | 'lightningcss'
• Default: 'cssnano'
• Description: Specifies the CSS minifier to use.
  • 'cssnano': JavaScript-based minifier with a wide range of optimizations.
  • 'lightningcss': Rust-based minifier for significantly faster performance.
• Example:

  pluginCssMinimizer({
    minifier: "lightningcss",
  });

cssnanoOptions

• Type: ConfigChain<CssMinimizerPlugin.BasePluginOptions & CssMinimizerPlugin.DefinedDefaultMinimizerAndOptions<CssNanoOptions>> | Function
• Default:

  {
    minify: CssMinimizerWebpackPlugin.cssnanoMinify,
    minimizerOptions: {
      preset: ['default', { mergeLonghand: false }],
    },
  }

• Description: Configuration for cssnano, applied when minifier is 'cssnano'. Can be an object merged with defaults or a function to modify options. See cssnano documentation for all available options.
• Sub-options:
  • configFile (string, optional): Path to a cssnano configuration file.
  • preset (string | [string, object], optional): Preset name and configuration (e.g., ['default', { mergeLonghand: false }]).
• Example (Object):

  pluginCssMinimizer({
    minifier: "cssnano",
    cssnanoOptions: {
      minimizerOptions: {
        preset: ["advanced", { discardComments: { removeAll: true } }],
      },
    },
  });

• Example (Function):

  pluginCssMinimizer({
    minifier: "cssnano",
    cssnanoOptions: (options) => {
      options.minimizerOptions = {
        preset: require.resolve("cssnano-preset-simple"),
      };
      return options;
    },
  });

lightningCssOptions

• Type: ConfigChain<CssMinimizerPlugin.BasePluginOptions & CssMinimizerPlugin.DefinedDefaultMinimizerAndOptions<LightningCssOptions>> | Function
• Default:

  {
    minify: CssMinimizerWebpackPlugin.lightningCssMinify,
    minimizerOptions: {
      targets: 'defaults',
    },
  }

• Description: Configuration for Lightning CSS, applied when minifier is 'lightningcss'. Can be an object merged with defaults or a function to modify options. See Lightning CSS documentation for all available options.
• Sub-options:
  • targets (string | string[] | { [key: string]: number }, optional): Browser targets using browserslist syntax (e.g., ['> 0.25%', 'not dead']) or version objects (e.g., { chrome: 80 }).
  • drafts (object, optional): Enable draft CSS features, such as { nesting: true }.
• Example (Object):

  pluginCssMinimizer({
    minifier: "lightningcss",
    lightningCssOptions: {
      minimizerOptions: {
        targets: ["chrome >= 80", "firefox >= 78"],
        drafts: { nesting: true },
      },
    },
  });

• Example (Function):

  pluginCssMinimizer({
    minifier: "lightningcss",
    lightningCssOptions: (options) => {
      options.minimizerOptions.targets = ["> 0.5%"];
      return options;
    },
  });

Full Example

// rsbuild.config.ts
import { pluginCssMinimizer } from "rsbuild-plugin-css-optimizer";

export default {
  output: {
    minify: {
      css: true, // Enable CSS minification
    },
  },
  plugins: [
    pluginCssMinimizer({
      minifier: "lightningcss",
      lightningCssOptions: {
        minimizerOptions: {
          targets: ["> 0.25%", "not dead"],
          drafts: { nesting: true },
        },
      },
    }),
    // Alternatively, use cssnano
    pluginCssMinimizer({
      minifier: "cssnano",
      cssnanoOptions: {
        minimizerOptions: {
          preset: ["default", { discardComments: { removeAll: true } }],
        },
      },
    }),
  ],
};

Performance

• Lightning CSS:
  • Speed: 5-10x faster than cssnano due to Rust’s compiled performance and parallel processing.
  • Use Case: Ideal for large projects or frequent builds where build speed is critical.
• cssnano:
  • Speed: Slower but provides extensive optimization plugins for fine-grained control.
  • Use Case: Best for projects prioritizing minimal CSS output size over build performance.

Notes

• Source Maps: Enable source maps in Rsbuild with devtool: 'source-map' for both minifiers.
• Browser Targets: For Lightning CSS, use browserslist syntax (e.g., ['> 0.25%']) or version objects (e.g., { chrome: 80 }). The default ('defaults') targets modern browsers.
• cssnano Compatibility: The mergeLonghand: false default prevents issues with properties like safe-area-inset-top (see cssnano issue #803).
• Production Only: Minification applies only in production builds when isProd is true and minify.css is enabled.

Troubleshooting

• Minification Not Applied:
  • Verify output.minify.css is true or minify is true in your Rsbuild config.
  • Ensure the build is in production mode (isProd: true).
• Invalid Options:
  • Check TypeScript errors for incorrect cssnanoOptions or lightningCssOptions.
  • Refer to cssnano or Lightning CSS documentation for valid options.

Contributing

Contributions are welcome! Please submit issues or pull requests to the plugin repository.

License

MIT