Lightning CSS Plugin#

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 add @rsbuild/plugin-lightningcss -D

Register Plugin#

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

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 lightningcss from 'lightningcss';

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