#output.cssModules

• Type: CSSModules

Configure custom CSS Modules settings.

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

#cssModules.auto

The auto option enables CSS Modules automatically based on filenames.

• Type:

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

• Default: true

Type descriptions:

• true: Enable CSS Modules for files ending in .module.* (recommended). Also supports .modules.*.
• false: Disable CSS Modules.
• RegExp: Enable CSS Modules for files that match the regular expression, using the flags you specify.
• function: Enable CSS Modules for files based on the filename satisfying your filter function check.

For example, to additionally enable CSS Modules for files in the shared/ directory:

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

You can also use a regular expression to replace the default matching rule. For example, to enable CSS Modules for files ending in .module.* or a custom .scoped.* suffix:

export default {
  output: {
    cssModules: {
      auto: /\.(module|scoped)\.\w+$/i,
    },
  },
};

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

#Example

Suppose you have the following CSS file:

.dash-class {
  color: blue;
}
.camelClass {
  color: red;
}
.underscore_class {
  color: green;
}

Different exportLocalsConvention configurations will produce different export results:

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

console.log(styles);
// camelCase (default)
// { 'dash-class': '...', 'dashClass': '...', 'camelClass': '...', 'underscore_class': '...', 'underscoreClass': '...' }

// camelCaseOnly
// { 'dashClass': '...', 'camelClass': '...', 'underscoreClass': '...' }

// dashes
// { 'dash-class': '...', 'dashClass': '...', 'camelClass': '...', 'underscore_class': '...' }

// dashesOnly
// { 'dashClass': '...', 'camelClass': '...', 'underscore_class': '...' }

// asIs
// { 'dash-class': '...', 'camelClass': '...', 'underscore_class': '...' }

#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);

#Placeholders

You can use the following placeholders 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. hashDigest is the hash encodings, and hashDigestLength is the length of the hash value.

#Example

Set localIdentName to other value, for example, the shorter 5-character hash value:

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

#cssModules.mode

• Type:

type Mode =
  | 'local'
  | 'global'
  | 'pure'
  | 'icss'
  | ((
      resourcePath: string,
      resourceQuery: string,
      resourceFragment: 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': Selectors are global by default. Use :local for locally scoped selectors. @value processing remains enabled.
3. 'pure': Uses local scoping and requires each selector to contain at least one local class or ID. It does not automatically remove unused CSS classes.
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 cssModules.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:

export default {
  output: {
    cssModules: {
      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);