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.

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.

pluginLightningcss({
  transform: 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,
});