Solving Jest Testing Challenges with ES Modules
June 18, 2025
~2 min read
TestingJavaScriptReact
Solving Jest Testing Challenges with ES Modules
When working with modern JavaScript libraries that use ES modules, you might encounter testing issues, especially when integrating them into Create React App projects. One common error is
SyntaxError: Cannot use import statement outside a module. Here's how I solved this frustrating problem.The Problem
I recently built a component library using Vite, which outputs ES modules by default. When I tried to use this library in a Create React App project that uses Jest for testing, I encountered a roadblock. Jest couldn't process the ES module imports from my component library, resulting in the dreaded error:
bash
1SyntaxError: Cannot use import statement outside a moduleThis happens because Jest, by default, uses Node's CommonJS module system, while my component library was using ES modules. The two systems have different import/export syntax, causing the conflict.
The Solution
After much research and experimentation, I found a working solution that involves two key parts:
1. Configure Jest to Transform Node Modules
By default, Jest ignores transformations for files in
node_modules. We need to tell Jest to transform our component library files specifically:javascript
1// jest.config.js
2module.exports = {
3 verbose: true,
4 roots: ["<rootDir>/src"],
5 coverageDirectory: "coverage",
6 collectCoverageFrom: [...],
7 coverageThreshold: {
8 global: {
9 statements: 100,
10 branches: 100,
11 functions: 100,
12 lines: 100
13 }
14 },
15 coverageReporters: ["json", "html", "text-summary"],
16 transform: {
17 "^.+\\.(ts|tsx)$": "ts-jest",
18 "^.+\\.(js|jsx)$": "babel-jest", // Important
19 "^.+\\.svg$": "<rootDir>/svgTransform.js",
20 },
21 testMatch: ["**/?(*.)+(spec|test).ts?(x)"],
22 moduleFileExtensions: ["ts", "tsx", "js", "jsx", "json", "node"],
23 testEnvironment: "jsdom",
24 testEnvironmentOptions: {
25 resources: "usable",
26 },
27 transformIgnorePatterns: ["<rootDir>/node_modules/(?!(my-component-lib)/)"], // Important
28 moduleDirectories: ["node_modules", "src"]
29The crucial parts here are:
- Adding
babel-jestto transform JavaScript files - Setting
transformIgnorePatternsto exclude your component library from the ignored modules
2. Configure Babel
Next, we need to set up Babel to properly transform our ES modules:
javascript
1// .babelrc
2module.exports = {
3 presets: [
4 ['@babel/preset-env', { targets: { node: 'current' } }],
5 '@babel/preset-typescript',
6 '@babel/preset-react'
7 ],
8};Don't forget to install the necessary dependencies:
bash
1npm install --save-dev @babel/preset-env @babel/preset-typescript @babel/preset-reactRunning Tests
Finally, I added a script to my package.json to run the tests with the custom configuration:
json
1"jest": "jest --config jest.config.js --coverage"With these changes in place, Jest was able to properly transform my ES module component library, and the tests ran successfully.
Why This Works
The solution works because:
- We're telling Jest to transform our component library files with Babel instead of ignoring them
- Babel converts the ES modules to a format Jest can understand
- The specific Babel presets handle both TypeScript and React JSX syntax
Conclusion
Testing modern JavaScript libraries that use ES modules with Jest requires some configuration, but it's definitely possible. The key is to properly set up your transformation patterns and Babel configuration to handle the ES module syntax.
This solution should work for most cases where you're testing applications that use ES module libraries with Jest. If you're working with Next.js, you might also consider using the
transpilePackages option in your Next.js config.