output.cssModules

  • Type:
type CSSModules = {
  auto?:
    | boolean
    | RegExp
    | ((
        resourcePath: string,
        resourceQuery: string,
        resourceFragment: string,
      ) => boolean);
  localIdentName?: string;
  exportLocalsConvention?: CSSModulesLocalsConvention;
};

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 not to be removed from the locals.
  • camelCaseOnly Class names will be camelized, the original class name will be removed from the locals.
  • dashes Only dashes in class names will be camelized.
  • dashesOnly Dashes in class names will be camelized, the original class name will be removed from the locals.
export default {
  output: {
    cssModules: {
      exportLocalsConvention: 'camelCaseOnly',
    },
  },
};

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

style.module.css
:global(.blue) {
  color: blue;
}

.red {
  color: red;
}

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

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

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