> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# CSS Modules

[CSS Modules](https://github.com/css-modules/css-modules) allows you to write CSS in a modular way, and import these styles in JavaScript files. CSS Modules automatically generates unique class names, isolating styles between modules and avoiding class name conflicts.

Rsbuild supports CSS Modules by default without additional configuration. Our convention is to use the `[name].module.css` filename to enable CSS Modules.

The following style files are considered CSS Modules:

- `*.module.css`
- `*.module.less`
- `*.module.sass`
- `*.module.scss`
- `*.module.styl`
- `*.module.stylus`

## Usage example

Write styles in a `*.module.css` file:

```css title="button.module.css"
.red {
  background: red;
}
```

Import styles in a JavaScript file:

```tsx title="Button.tsx"
import styles from './button.module.css';

export default () => {
  return <button className={styles.red}>Button</button>;
};
```

After compilation, CSS Modules class names are automatically appended with a hash value to prevent class name conflicts:

```css
/* classnames generated in development mode */
.src-App-module__red-hiQIE4 {
  background: red;
}

/* classnames generated in production mode */
.red-hiQIE4 {
  background: red;
}
```

:::tip
See [Custom Class Names](#custom-class-names) to modify the class name generation rules.
:::

## Named import

If you prefer to use named imports in CSS Modules, you can enable it through the [output.cssModules.namedExport](/config/output/css-modules.md#cssmodulesnamedexport) config.

```ts title="rsbuild.config.ts"
export default {
  output: {
    cssModules: {
      namedExport: true,
    },
  },
};
```

If enabled, you can reference class names using named imports:

```tsx title="Button.tsx"
import { red } from './button.module.css';

export default () => {
  return <button className={red}>Button</button>;
};
```

## CSS Modules recognition rules

By default, only files ending with `*.module.css` are recognized as CSS Modules.

If you want to treat other CSS files as CSS Modules, you can configure [output.cssModules.auto](/config/output/css-modules.md#cssmodulesauto).

For example:

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

After this configuration, the following two files will be recognized as CSS Modules:

```ts
import styles1 from './foo.module.css';
import styles2 from './shared/bar.css';
```

## Custom class names

Customizing class names generated by CSS Modules is a commonly used feature. You can configure this using [output.cssModules.localIdentName](/config/output/css-modules.md#cssmoduleslocalidentname).

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

If you need to customize other configs of CSS Modules, you can set them via [output.cssModules](/config/output/css-modules.md).

## Global styles

In some cases, you may need to use global styles in CSS Modules, such as overriding the styles of third-party libraries or setting global styles for specific elements.

CSS Modules provides the `:global()` pseudo-class selector for this purpose. Selectors inside `:global()` retain their original class names, allowing them to correctly match global elements.

```css title="styles.module.css"
/* Local selectors, will be hashed */
.container {
  padding: 20px;
}

/* Global selectors, will not be hashed */
:global(.foo) {
  color: red;
}

/* Use local and global selectors together, only .wrapper will be hashed */
.wrapper :global(.bar) {
  margin: 10px;
}
```

You can also nest `:global()`:

```css title="card.module.css"
.card {
  /* Only affects .btn elements inside .card */
  :global(.btn) {
    background: blue;
  }
}
```

## Type declaration

When you import CSS Modules in TypeScript code, TypeScript may prompt that the module is missing a type definition:

```
TS2307: Cannot find module './index.module.css' or its corresponding type declarations.
```

To fix this, use one of the following methods:

- Method 1: If the `@rsbuild/core` package is installed, you can add the [preset types](/guide/basic/typescript.md#preset-types) provided by `@rsbuild/core` to `tsconfig.json`:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "types": ["@rsbuild/core/types"]
  }
}
```

- Method 2: Manually add the required type declarations:

```ts title="src/env.d.ts"
declare module '*.module.css' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.scss' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.sass' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.less' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.styl' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
declare module '*.module.stylus' {
  const classes: { readonly [key: string]: string };
  export default classes;
}
```

- Method 3: If you need to use **named imports** to reference class names, you can use a looser type declaration:

```ts title="src/env.d.ts"
declare module '*.module.css';
declare module '*.module.scss';
declare module '*.module.sass';
declare module '*.module.less';
declare module '*.module.styl';
declare module '*.module.stylus';
```

After adding the type declaration, if the type error persists, try restarting your IDE or adjusting the directory where `env.d.ts` is located to ensure TypeScript can correctly identify the type definition.

## Type generation

The above method provides types for CSS Modules, but cannot accurately indicate which class names are exported by a specific CSS file.

Rsbuild supports generating accurate type declarations for CSS Modules. Register the [@rsbuild/plugin-typed-css-modules](https://github.com/rstackjs/rsbuild-plugin-typed-css-modules) plugin and run the build to generate type declaration files for all CSS Modules.

```ts title="rsbuild.config.ts"
import { pluginTypedCSSModules } from '@rsbuild/plugin-typed-css-modules';

export default {
  plugins: [pluginTypedCSSModules()],
};
```

### Example

For example, create two files named `src/index.ts` and `src/index.module.css`:

```tsx title="src/index.ts"
import styles from './index.module.css';

console.log(styles.pageHeader);
```

```css title="src/index.module.css"
.page-header {
  color: black;
}
```

After building, Rsbuild will generate a `src/index.module.css.d.ts` type declaration file:

```ts title="src/index.module.css.d.ts"
interface CssExports {
  'page-header': string;
  pageHeader: string;
}
declare const cssExports: CssExports;
export default cssExports;
```

Now when you open the `src/index.ts` file, you'll see that the `styles` object has accurate types.