Lightning CSS Plugin

About Lightning CSS

Lightning CSS is a high performance CSS parser, transformer and minifier written in Rust. It supports parsing and transforming many modern CSS features into syntax supported by target browsers, and also provides a better compression ratio.

The Lightning CSS plugin will use lightningcss-loader to replace the builtin postcss-loader in Rsbuild to reduce the performance overhead of PostCSS and autoprefixer, and will use LightningCSSMinifyPlugin to replace the default builtin CSS minifier in Rspack to obtain greater compression ratios.

Quick Start

Install Plugin

You can install the plugin using the following command:

npm
yarn
pnpm
bun
npm add @rsbuild/plugin-lightningcss -D

Register Plugin

You can register the plugin in the rsbuild.config.ts file:

rsbuild.config.ts
import { pluginLightningcss } from '@rsbuild/plugin-lightningcss';

export default {
  plugins: [pluginLightningcss()],
};

Notes

After enabling Lightning CSS as a transformer, PostCSS-based configurations and features will not be available, such as tools.postcss, tools.autoprefixer and Tailwind CSS. The problem of not being able to be used with Tailwind CSS is expected to be resolved in Tailwind CSS V4 in the future.

Options

transform

Use lightningcss-loader instead of Rsbuild's builtin postcss-loader to transform CSS files. For options passed to lightningcss-loader, please refer to the lightningcss Repo for detailed usage.

  • Type: false | lightningcss.TransformOptions<CustomAtRules>
  • Default:
const defaultOptions = {
  targets: browserslistToTargets(browserslist),
};
  • Example: Enable or disable lightningcss features, which can be configured by importing a lightningcss instance from the plugin.
import { lightningcss, pluginLightningcss } from '@rsbuild/plugin-lightningcss';

pluginLightningcss({
  transform: {
    include: lightningcss.Features.Nesting,
  },
});
  • Example: Convert all length units to rem through lightningcss's custom visitor.
pluginLightningcss({
  transform: {
    visitor: {
      Length(len) {
        return {
          unit: 'rem',
          value: len.value,
        };
      },
    },
  },
});
  • Example: Enable lightningcss-loader only in the development build, still use postcss-loader in the production build
pluginLightningcss({
  transform: process.env.NODE_ENV === 'development',
});
  • Example: Disable CSS transform of lightningcss, leaving only CSS minify.
pluginLightningcss({
  transform: false,
});

minify

Use Lightning CSS instead of Rspack's builtin CSS minifier. For options passed to lightningcss, please refer to the lightningcss repository for detailed usage.

  • Type: false | lightningcss.TransformOptions<CustomAtRules>
  • Default:
const defaultOptions = {
  targets: browserslistToTargets(browserslist(browserslistUserConfig)),
};
  • Example: Disable lightning CSS minify for ColorFunctions and HexAlphaColors
import { lightningcss, pluginLightningcss } from '@rsbuild/plugin-lightningcss';

pluginLightningcss({
  minify: {
    exclude:
      lightningcss.Features.ColorFunction |
      lightningcss.Features.HexAlphaColors,
  },
});
  • Example: Disable the CSS minify of lightningcss, leaving only the CSS transform.
pluginLightningcss({
  minify: false,
});

implementation

Used to inject lightningcss instance. This configuration can be used when a lightningcss instance has been installed and exists in the project.

  • Type: typeof import('lightningcss')
  • Example:
import { pluginLightningcss } from '@rsbuild/plugin-lightningcss';
import * as lightningcss from 'lightningcss';

pluginLightningcss({
  implementation: lightningcss,
  minify: {
    exclude: lightningcss.Features.ColorFunction,
  },
});