Jest Module Name Mapper Not Working Fix

In this tutorial, you'll learn about Jest Module Name Mapper Not Working Fix. We cover key concepts, practical examples, and best practices.

Your tests fail with Cannot find module '@components/Button' even though the import works in your application code with webpack or TypeScript path aliases.

The Problem

// WRONG — importing with alias that Jest doesn't understand
import Button from '@components/Button';

Cannot find module '@components/Button' from 'src/pages/Home.test.js'

Your application uses path aliases (webpack resolve.alias or TypeScript paths), but Jest uses Node's module resolution by default and doesn't know about these aliases.

Step-by-Step Fix

1. Configure moduleNameMapper

// RIGHT — Jest config with module aliases
module.exports = {
  moduleNameMapper: {
    '^@components/(.*)$': '<rootDir>/src/components/$1',
    '^@utils/(.*)$': '<rootDir>/src/utils/$1',
    '^@services/(.*)$': '<rootDir>/src/services/$1',
    '^@/(.*)$': '<rootDir>/src/$1',
  },
};

2. Mock non-JS files

// RIGHT — mock CSS, images, and other assets
module.exports = {
  moduleNameMapper: {
    '\\.(css|less|scss)$': '<rootDir>/__mocks__/styleMock.js',
    '\\.(jpg|jpeg|png|gif|svg)$': '<rootDir>/__mocks__/fileMock.js',
    '\\.(mp3|mp4|webm)$': '<rootDir>/__mocks__/fileMock.js',
  },
};

Contents of __mocks__/styleMock.js:

module.exports = {};

Contents of __mocks__/fileMock.js:

module.exports = 'test-file-stub';

3. Sync with TypeScript paths

// RIGHT — match tsconfig paths
// tsconfig.json
// {
//   "compilerOptions": {
//     "paths": {
//       "@/*": ["./src/*"],
//       "@components/*": ["./src/components/*"]
//     }
//   }
// }

// jest.config.js
module.exports = {
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',
    '^@components/(.*)$': '<rootDir>/src/components/$1',
  },
};

4. Use moduleDirectories for simple cases

// RIGHT — for src/ root imports
module.exports = {
  moduleDirectories: ['node_modules', 'src'],
};

// Now this works without aliases:
import Button from 'components/Button';

Expected output:

PASS  tests/module.test.js
  ✓ imports with alias (4 ms)
  ✓ mocks CSS imports (3 ms)

Prevention Tips

• Keep moduleNameMapper in sync with webpack/TypeScript aliases
• Mock all non-JS file imports (CSS, images, fonts)
• Use <rootDir> for absolute paths in mappings
• Use ^ and $ anchors in patterns for precise matching
• Consider using moduleDirectories for simple setups

Common Mistakes with config module name

1. Using foldl instead of foldl' causing stack overflow on large lists
2. Forgetting deriving (Show, Eq) on custom data types needed for debugging
3. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable

These mistakes appear frequently in real-world JEST code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ