website/docs/en/guide/tech/css.mdx
import { PackageManagerTabs } from '@theme';
Rspack has built-in support for CSS and provides several features to support CSS bundling.
You can choose from the following options:
Rspack supports the following three CSS module types which you can configure manually:
css/auto: Automatically determines whether a file is a normal CSS file or CSS Modules based on the file extension. Files ending with *.module.css are treated as CSS Modules.css: Used to handle normal CSS files.css/module: Used to handle CSS Modules.To enable CSS support, add CSS rules to your configuration:
export default {
module: {
rules: [
{
test: /\.css$/i,
type: 'css/auto',
},
{
test: /\.module\.css$/i,
type: 'css/module',
},
],
},
};
You can also configure type: 'css/auto' to customize which files are treated as CSS files. For example, treat .less files as CSS files:
export default {
module: {
rules: [
{
test: /\.less$/,
type: 'css/auto', // 👈
use: ['less-loader'],
},
],
},
};
Rspack supports using css-loader and CssExtractRspackPlugin to generate standalone CSS files.
If you are migrating a webpack project that uses mini-css-extract-plugin, it is recommended to replace it with CssExtractRspackPlugin. Their functionality and options are basically the same.
import { rspack } from '@rspack/core';
export default {
module: {
rules: [
{
test: /\.css$/i,
use: [rspack.CssExtractRspackPlugin.loader, 'css-loader'],
type: 'javascript/auto',
},
],
},
plugins: [new rspack.CssExtractRspackPlugin({})],
};
Refer to the migration guide to learn how to migrate from webpack.
:::tip
CssExtractRspackPlugin cannot be used with type: 'css', type: 'css/auto', or type: 'css/module' as these types are provided by native css support.
:::
Rspack supports using css-loader and style-loader to inject CSS via <style> tags. This method does not generate standalone CSS files but inline the CSS content into JS files.
export default {
module: {
rules: [
{
test: /\.css$/i,
use: ['style-loader', 'css-loader'],
type: 'javascript/auto',
},
],
},
};
:::tip
style-loader cannot be used with type: 'css', type: 'css/auto', or type: 'css/module' as these types are provided by native css support.
:::
CSS Modules is a way of organizing CSS files that localizes the scope of CSS by automatically generating unique identifiers for class names. This allows you to use the same class name in different files without worrying about collisions.
If you enable Built-in CSS support, Rspack will treat files with a *.module.css extension as CSS Modules by default. You can import them into your JavaScript files, and then access each class defined in the CSS file as an export from the module.
.red {
color: red;
}
You can use namespace import:
import * as styles from './index.module.css';
document.getElementById('element').className = styles.red;
You can also use named import:
import { red } from './index.module.css';
document.getElementById('element').className = red;
To enable default imports in Rspack, you need to set namedExports to false in your Rspack configuration file. This allows you, when using CSS Modules, to import the entire style module by default import, in addition to namespace imports and named imports:
export default {
module: {
parser: {
'css/auto': {
namedExports: false,
},
},
},
};
Now you can use default import:
import styles from './index.module.css';
document.getElementById('element').className = styles.red;
:::tip
Rspack provides options to customize the parsing and generation of CSS Modules:
:::
If you do not enable Rspack's built-in CSS support, you can use css-loader to provide CSS Modules support.
Enable the modules option of css-loader:
export default {
module: {
rules: [
{
test: /\.css$/i,
loader: 'css-loader',
type: 'javascript/auto',
options: {
modules: true,
},
},
],
},
};
For more usage, please refer to css-loader - modules.
Rspack supports postcss-loader, which you can configure like this:
<PackageManagerTabs command="add postcss postcss-loader -D" />export default {
module: {
rules: [
{
test: /\.css$/,
use: [
{
loader: 'postcss-loader',
options: {
postcssOptions: {
// ...
},
},
},
],
// set to 'css/auto' if you want to support '*.module.css' as CSS Modules, otherwise set type to 'css'
type: 'css/auto',
},
],
},
};
The above configuration will have all *.css files processed by postcss-loader. The output will be passed to Rspack for CSS post-processing.
Rspack supports sass-loader, which you can configure like this:
<PackageManagerTabs command="add sass-embedded sass-loader -D" />export default {
module: {
rules: [
{
test: /\.(sass|scss)$/,
use: [
{
loader: 'sass-loader',
options: {
// using `modern-compiler` and `sass-embedded` together significantly improve build performance,
// requires `sass-loader >= 14.2.1`
api: 'modern-compiler',
implementation: require.resolve('sass-embedded'),
},
},
],
// set to 'css/auto' if you want to support '*.module.(scss|sass)' as CSS Modules, otherwise set type to 'css'
type: 'css/auto',
},
],
},
};
The above configuration runs all *.sass and *.scss files through the sass-loader and passes the resulting results to Rspack for CSS post-processing.
Rspack supports less-loader, which you can configure like this:
<PackageManagerTabs command="add less less-loader -D" />export default {
module: {
rules: [
{
test: /\.less$/,
use: [
{
loader: 'less-loader',
options: {
// ...
},
},
],
// set to 'css/auto' if you want to support '*.module.less' as CSS Modules, otherwise set type to 'css'
type: 'css/auto',
},
],
},
};
The above configuration runs all *.less files through the less-loader and passes the generated results to Rspack for CSS post-processing.
Tailwind CSS is a CSS framework and design system based on utility class, which can quickly add common styles to components, and support flexible extension of theme styles.
Tailwind CSS documentation provides integration guides for Rspack, please refer to: