#CSS

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 to customize CSS file processing.

#Lightning CSS

Rsbuild uses Rspack's built-in lightningcss-loader to transform CSS code. It automatically reads the project's browserslist config and converts 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 without worrying about browser compatibility.
• Use tools.lightningcssLoader to customize lightningcss-loader options.

#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 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 using 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 another CSS minimizer.

#PostCSS

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

#Configuration file

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,
  },
};

postcss-load-config supports multiple file formats, including but not limited to the following file names:

• postcss.config.js
• postcss.config.mjs
• postcss.config.cjs
• postcss.config.ts
• ...

#tools.postcss

You can also 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);
    },
  },
};

#Configuration priority

• 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.

#CSS Modules

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

#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

See CSS-in-JS 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.

To inline styles into your JS file, 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 from node_modules

Rsbuild supports importing CSS files from 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';

#Query parameters

#inline

Rsbuild supports importing compiled CSS files as strings in JavaScript by using the ?inline query parameter.

import inlineCss from './style.css?inline';

console.log(inlineCss); // Compiled CSS content

Using import "*.css?inline" has the following behaviors:

• Get the compiled text content of the CSS file, processed by Lightning CSS, PostCSS and CSS preprocessors
• The content will be inlined into the final JavaScript bundle
• No separate CSS file will be generated

#raw

Rsbuild supports importing raw CSS files as strings in JavaScript by using the ?raw query parameter.

import rawCss from './style.css?raw';

console.log(rawCss); // Output the raw content of the CSS file

Using import "*.css?raw" has the following behaviors:

• Get the raw text content of the CSS file, without any preprocessing or compilation
• The content of the CSS file will be inlined into the final JavaScript bundle
• No separate CSS file will be generated