Import CSS Files#

Rsbuild provides out-of-the-box support for CSS, including PostCSS, CSS Modules, CSS preprocessors, CSS inlining, and CSS compression.

Rsbuild also provides several configurations that allow customization of the processing rules for CSS files.

Lightning CSS#

Rsbuild uses Rspack's built-in lightningcss-loader to transform CSS code. It automatically reads the project's browserslist config and converts the CSS code to syntax supported by target browsers.

Features#

• Lightning CSS automatically adds vendor prefixes like -webkit-, -moz-, -ms-, etc., so you don't need to manually add prefixes or use the autoprefixer plugin.
• Lightning CSS automatically downgrades CSS syntax, allowing you to use modern CSS features such as CSS nesting and custom media queries in your code without worrying about browser compatibility issues.
• You can use tools.lightningcssLoader to customize the options for lightningcss-loader.

Disabling Lightning CSS#

If Lightning CSS does not meet your needs, you can disable Lightning CSS and use PostCSS to transform your CSS code.

Steps:

1. Set tools.lightningcssLoader to false to disable the Lightning CSS loader.
2. Use @rsbuild/plugin-css-minimizer to switch the CSS minifier from Lightning CSS to cssnano or another CSS minifier.

import { pluginCssMinimizer } from '@rsbuild/plugin-css-minimizer';

export default {
  plugins: [pluginCssMinimizer()],
  tools: {
    lightningcssLoader: false,
  },
};

3. Refer to Using PostCSS to configure the PostCSS plugins you need. Here are some commonly used PostCSS plugins:

• autoprefixer: Adds vendor prefixes.
• postcss-preset-env: Converts modern CSS into something most browsers can understand.
• postcss-nesting: Supports CSS nesting.

CSS Minification#

When building for production, Rsbuild enables Rspack's built-in LightningCssMinimizerRspackPlugin plugin to minify CSS assets for better transmission efficiency.

• You can disable CSS minification through the output.minify option or customize the options for LightningCssMinimizerRspackPlugin.
• You can use @rsbuild/plugin-css-minimizer to customize the CSS minimizer, switching to cssnano or other CSS minimizer.

Using PostCSS#

Rsbuild supports transforming CSS code through PostCSS. You can configure PostCSS in the following ways:

1. Rsbuild uses postcss-load-config to load the PostCSS configuration file in the root directory of the current project, such as postcss.config.js:

module.exports = {
  'postcss-px-to-viewport': {
    viewportWidth: 375,
  },
};

2. Configure the postcss-loader through Rsbuild's tools.postcss option, which supports modifying the built-in configuration through a function, for example:

export default {
  tools: {
    postcss: (opts) => {
      const viewportPlugin = require('postcss-px-to-viewport')({
        viewportWidth: 375,
      });
      opts.postcssOptions.plugins.push(viewportPlugin);
    },
  },
};

• When you configure both the postcss.config.js file and the tools.postcss option, both will take effect, and the tools.postcss option will take precedence.
• If there is no postcss.config.js file in the project and the tools.postcss option is not configured, Rsbuild will not register postcss-loader.

Using CSS Modules#

Rsbuild supports CSS Modules by default, please read the Using CSS Modules chapter for the complete usage of CSS Modules.

Using CSS preprocessors#

Rsbuild supports popular CSS preprocessors through plugins, including Sass, Less and Stylus. See how to use them:

• Sass Plugin
• Less Plugin
• Stylus Plugin

CSS-in-JS#

Please read the React - CSS-in-JS section to learn how to use common CSS-in-JS libraries in Rsbuild.

Inline CSS Files#

By default, Rsbuild will extract CSS into a separate .css file and output it to the dist directory.

If you want to inline styles into your JS file, you can set output.injectStyles to true to disable CSS extraction logic. When the JS file is requested by the browser, JS dynamically inserts the <style> tag into the Html to load the CSS styles.

export default {
  output: {
    injectStyles: true,
  },
};

This will increase the size of your JS Bundle, so it is usually not recommended to disable the CSS extraction.

Import CSS in node_modules#

Rsbuild supports importing CSS files in node_modules.

• Import in a JS file:

/* reference normalize.css */
/* https://github.com/necolas/normalize.css */
import 'normalize.css';

• Import in a CSS file:

@import 'normalize.css';

body {
  /* */
}

In Sass and Less files, it is also allowed to add the ~ prefix to resolve style files in node_modules. However, this is a deprecated feature and it is recommended to remove the ~ prefix from the code.

@import 'normalize.css';