jest-css-modules-transform

4.4.2 verified Sat Apr 25 auth: no javascript

A Jest preprocessor that transforms CSS, SCSS, SASS, Less, and Stylus files into JavaScript objects mimicking Webpack's css-loader module output. Version 4.4.2 is current stable; released occasionally with bug fixes and minor features. Unlike simple identity mock objects (e.g., `{}`), this generates correct class name mappings (as-is, camelCase, dashes), supports PostCSS with custom plugins, and allows prepending variables or mixins. It provides configuration via `jest-css-modules-transform-config.js` for per-preprocessor options, making it ideal for visual regression testing or component testing where real class names matter.

Common errors

error Cannot find module 'sass' or 'node-sass' ↓

cause Missing dependency for processing scss files.

fix

Run 'npm install sass --save-dev' or 'npm install node-sass --save-dev'.

error TypeError: Cannot read property 'includes' of undefined ↓

cause Options file exports a function instead of an object.

fix

Ensure 'jest-css-modules-transform-config.js' exports a plain object.

error Module parse failed: Unexpected token (1:0) in file styles.css ↓

cause Jest transform mapping missing for CSS extension.

fix

Add '.+\.(css|styl|less|sass|scss)$' to transform in Jest config.

Warnings

gotcha Options file must be named exactly 'jest-css-modules-transform-config.js' and located in project root (where package.json is). ↓

fix Rename config file or move to root directory.

gotcha PostCSS processing only applies to .css, .pcss, .postcss files; other preprocessors (scss, less) are handled by their respective modules. ↓

fix Ensure postcss.config.js is in root or use postcssConfig in jest-css-modules-transform-config.js for non-.css files.

breaking Node.js <10 is not supported; package uses modern JavaScript features. ↓

fix Upgrade Node to version 10 or higher.

gotcha The 'sass' module is preferred over 'node-sass' for scss processing; if both exist, 'sass' is used unless sassModuleName is set. ↓

fix Install 'sass' as a devDependency or set sassModuleName: 'node-sass' in config.

deprecated Option 'localIdentName' from webpack is not supported; use exportLocalsStyle instead. ↓

fix Use cssLoaderConfig.exportLocalsStyle to control class name format.

Install

npm install jest-css-modules-transform

yarn add jest-css-modules-transform

pnpm add jest-css-modules-transform

Imports

default
```
module.exports = require('jest-css-modules-transform'); // or in Jest config as string
```
This package is a Jest transform, not imported in test files. Configure in Jest's 'transform' option as a string.
process
```
In jest-css-modules-transform-config.js: module.exports = { ... };
```
Options are exported from a separate config file, not passed to the transform directly.

Quickstart

Shows basic setup for Jest transform configuration and optional config file for custom CSS module output style.

// jest.config.js
module.exports = {
  transform: {
    '^.+\\.(css|styl|less|sass|scss)$': 'jest-css-modules-transform',
  },
};

// Optionally create jest-css-modules-transform-config.js in project root
// to customize preprocessor options:
// jest-css-modules-transform-config.js
module.exports = {
  cssLoaderConfig: {
    exportLocalsStyle: 'camelCase',
  },
  postcssConfig: {
    plugins: [require('autoprefixer')],
  },
  prepend: ['src/variables.scss'],
};

// In your test file, import CSS as usual:
import styles from './styles.css';
expect(styles.myClass).toBeDefined();