Testing ECMAScript Modules with Jest

Fixing Jest's "Cannot use import statement outside a module" error by wiring up ESM support across package.json, TypeScript, and Jest config.

Takahiro Iwasa

2024-02-24

4 min read

When testing ECMAScript Modules (ESM) using Jest, you might encounter the error:

SyntaxError: Cannot use import statement outside a module

This happens when Jest runs a file containing import as CommonJS. Jest provides experimental ESM support, but it must be enabled consistently across Node.js, TypeScript, and Jest.

Creating ESM Package

First, create a new ESM package with the following commands:

mkdir jest-esm && cd jest-esm
npm init -y

Install the necessary development dependencies:

npm i -D typescript jest @types/jest ts-node ts-jest

Add "type": "module" to the package.json.

Your package.json should look like this:

1
{
2
  "name": "jest-esm",
3
  "version": "1.0.0",
4
  "description": "",
5
  "main": "index.js",
6
  "type": "module",
7
  "scripts": {
8
    "test": "echo \"Error: no test specified\" && exit 1"
9
  },
10
  "author": "",
11
  "license": "ISC",
12
  "devDependencies": {
13
    "@types/jest": "^29.5.12",
14
    "jest": "^29.7.0",
15
    "ts-jest": "^29.1.2",
16
    "ts-node": "^10.9.2",
17
    "typescript": "^5.3.3"
18
  }
19
}

Configuring TypeScript

Generate a tsconfig.json file with the following command:

npx tsc --init

Update the tsconfig.json file:

1
@@ -14 +14 @@
2
-    "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
3
+    "target": "es6",                                     /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
4
@@ -28 +28 @@
5
-    "module": "commonjs",                                /* Specify what module code is generated. */
6
+    "module": "es6",                                     /* Specify what module code is generated. */
7
@@ -30 +30 @@
8
-    // "moduleResolution": "node10",                     /* Specify how TypeScript looks up a file from a given module specifier. */
9
+    "moduleResolution": "node",                          /* Specify how TypeScript looks up a file from a given module specifier. */

Configuring Jest

Run the following command to set up Jest configuration:

Use Jest for the “test” script: Yes
Use TypeScript for the configuration: Yes
Test environment: jsdom
Add coverage reports: No
Provider for coverage: v8
Automatically clear mock calls…: No

npm init jest@latest

Edit the generated jest.config.ts to include:

1
// preset: undefined,
2
preset: 'ts-jest',

Supporting ESM

Update the test script in package.json to enable Node’s experimental VM modules:

1
"scripts": {
2
   "test": "jest"
3
   "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
4
}

Add the extensionsToTreatAsEsm configuration in jest.config.ts to indicate which file types Jest should treat as ESM:

1
extensionsToTreatAsEsm: ['.ts'],

To configure ESM in ts-jest, refer to the official documentation.

Update jest.config.ts with moduleNameMapper to handle .js extensions:

1
// moduleNameMapper: {},
2
moduleNameMapper: {
3
  '^(\\.{1,2}/.*)\\.js$': '$1',
4
},

Update the transform setting to support ESM:

1
// transform: undefined,
2
transform: {
3
  '^.+\\.tsx?$': [
4
    'ts-jest',
5
    {
6
      useESM: true,
7
    },
8
  ],
9
},

Creating an ESM Module

For demonstration, install the hast-util-from-html package:

npm i hast-util-from-html

The hast-util-from-html package is an ESM-only package. You can confirm this by examining node_modules/hast-util-from-html/index.js; its exports use ESM syntax:

1
/**
2
 * @typedef {import('hast-util-from-parse5')} DoNotTouchItRegistersData
3
 *
4
 * @typedef {import('./lib/index.js').ErrorCode} ErrorCode
5
 * @typedef {import('./lib/index.js').ErrorSeverity} ErrorSeverity
6
 * @typedef {import('./lib/index.js').OnError} OnError
7
 * @typedef {import('./lib/index.js').Options} Options
8
 */
9

10
export { fromHtml } from './lib/index.js';

Create index.ts:

1
import { fromHtml } from 'hast-util-from-html';
2

3
export default function JestEsm(): void {
4
  const root = fromHtml(
5
    '<span><a href="https://github.com">GitHub</a></span>',
6
    { fragment: true }
7
  );
8
  console.info(root);
9
}

Testing ESM

Create index.spec.ts:

1
import JestEsm from './index';
2

3
test('case1', () => {
4
  JestEsm();
5
});

Run the tests:

npm run test

If you see the error:

1
● Validation Error:
2

3
  Test environment jest-environment-jsdom cannot be found. Make sure the testEnvironment configuration option points to an existing node module.
4

5
  Configuration Documentation:
6
  https://jestjs.io/docs/configuration
7

8

9
As of Jest 28 "jest-environment-jsdom" is no longer shipped by default, make sure to install it separately.

Install the missing package:

npm i -D jest-environment-jsdom

Run the tests again:

npm run test

Expected output:

1
 PASS  ./index.spec.ts
2
  ✓ case1 (20 ms)
3

4
Test Suites: 1 passed, 1 total
5
Tests:       1 passed, 1 total
6
Snapshots:   0 total
7
Time:        1 s
8
Ran all test suites.

Conclusion

Configuring package.json, TypeScript, and Jest together got a test importing a real ESM package passing instead of failing with SyntaxError: Cannot use import statement outside a module.

Getting to that passing test required changes across four different layers — package.json’s type field, the TypeScript module settings, Jest’s own config, and the Node invocation flag for experimental VM modules — which is a good illustration of why “just add type: module” alone doesn’t fix the original error.

The moduleNameMapper rule removes a .js suffix from relative imports so Jest can resolve the corresponding TypeScript source file. Because this workaround is specific to how the test environment resolves ESM-style imports, document why it exists before reusing it in another project.

Back to posts