output.cssModules#

• Type: CSSModules

For custom CSS Modules configuration.

The CSS Modules feature of Rsbuild is based on the modules option of css-loader. You can refer to css-loader - modules to learn more.

cssModules.auto#

The auto configuration option allows CSS Modules to be automatically enabled based on their filenames.

• Type:

type Auto =
  | boolean
  | RegExp
  | ((
      resourcePath: string,
      resourceQuery: string,
      resourceFragment: string,
    ) => boolean);

• Default: true

Type description:

• true: enable CSS Modules for all files matching /\.module\.\w+$/i.test(filename) regexp.
• false: disable CSS Modules.
• RegExp: enable CSS Modules for all files matching /RegExp/i.test(filename) regexp.
• function: enable CSS Modules for files based on the filename satisfying your filter function check.

export default {
  output: {
    cssModules: {
      auto: (resource) => {
        return resource.includes('.module.') || resource.includes('shared/');
      },
    },
  },
};

cssModules.exportLocalsConvention#

Style of exported class names.

• Type:

type CSSModulesLocalsConvention =
  | 'asIs'
  | 'camelCase'
  | 'camelCaseOnly'
  | 'dashes'
  | 'dashesOnly';

• Default: 'camelCase'

Type description:

• asIs: Class names will be exported as is.
• camelCase: Class names will be camelized, the original class name will be exported.
• camelCaseOnly: Class names will be camelized, the original class name will not be exported.
• dashes: Only dashes in class names will be camelized, the original class name will be exported.
• dashesOnly: Dashes in class names will be camelized, the original class name will not be exported.

export default {
  output: {
    cssModules: {
      exportLocalsConvention: 'camelCaseOnly',
    },
  },
};

cssModules.exportGlobals#

• Type: boolean
• Default: false

Allows exporting names from global class names, so you can use them via import.

Example#

Set the exportGlobals to true:

export default {
  output: {
    cssModules: {
      exportGlobals: true,
    },
  },
};

Use :global() in CSS Modules:

:global(.blue) {
  color: blue;
}

.red {
  color: red;
}

Then you can import the class name wrapped with :global():

import styles from './style.module.css';

console.log(styles.blue); // 'blue'
console.log(styles.red); // 'red-[hash]'

cssModules.localIdentName#

• Type: string
• Default:

// isProd indicates that the production build
const localIdentName = isProd
  ? '[local]-[hash:base64:6]'
  : '[path][name]__[local]-[hash:base64:6]';

Sets the format of the class names generated by CSS Modules after compilation.

Default Value#

localIdentName has different default values in development and production.

In a production, Rsbuild will generate shorter class names to reduce the bundle size.

import styles from './index.module.scss';

// In development, the value is `src-index-module__header-[hash]`
// In production, the value is `header-[hash]`
console.log(styles.header);

Template String#

You can use the following template strings in localIdentName:

• [name] - the basename of the asset.
• [local] - original class.
• [hash] - the hash of the string.
• [folder] - the folder relative path.
• [path] - the relative path.
• [file] - filename and path.
• [ext] - extension with leading dot.
• [hash:<hashDigest>:<hashDigestLength>]: hash with hash settings.

Example#

Set localIdentName to other value:

export default {
  output: {
    cssModules: {
      localIdentName: '[hash:base64:4]',
    },
  },
};

cssModules.mode#

• Type:

type Mode =
  | 'local'
  | 'global'
  | 'pure'
  | 'icss'
  | ((resourcePath: string) => 'local' | 'global' | 'pure' | 'icss');

• Default: 'local'

Controls the mode of compilation applied to the CSS Modules.

Optional values#

cssModules.mode can take one of the following values:

1. 'local' (default): This enables the CSS Modules specification for scoping CSS locally. Class and ID selectors are rewritten to be module-scoped, and @value bindings are injected.
2. 'global': This opts-out of the CSS Modules behavior, disabling both local scoping and injecting @value bindings. Global selectors are preserved as-is.
3. 'pure': This enables dead-code elimination by removing any unused local classnames and values from the final CSS. It still performs local scoping and @value injection.
4. 'icss': This compiles to the low-level Interoperable CSS format, which provides a syntax for declaring :import and :export dependencies between CSS and other languages. It does not perform any scoping or @value injection.

The 'local' mode is the most common use case for CSS Modules, enabling modular and locally-scoped styles within components. The other modes may be used in specific scenarios.

For example:

export default {
  output: {
    cssModules: {
      mode: 'global',
    },
  },
};

Function#

You can also pass a function to modules.mode that determines the mode based on the resource path, query, or fragment. This allows you to use different modes for different files.

For example, to use local scoping for .module.css files and global styles for other files:

modules: {
  mode: (resourcePath) => {
    if (/\.module\.\css$/.test(resourcePath)) {
      return 'local';
    }
    return 'global';
  };
}

cssModules.namedExport#

• Type: boolean
• Default: false

Whether to enable ES modules named export for class names.

export default {
  output: {
    cssModules: {
      namedExport: true,
    },
  },
};

Example#

.foo {
  color: blue;
}

• namedExport: false:

import styles from './style.module.css';

console.log(styles.foo);

• namedExport: true:

import { foo } from './style.module.css';
// or
import * as styles from './style.module.css';

console.log(foo);
console.log(styles.foo);

When `namedExport` is set to true, the `default` class exported by CSS Modules will be automatically renamed to `_default` class because `default` is a reserved word in ECMA modules.