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

5 min read

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

SyntaxError: Cannot use import statement outside a module

This issue arises because the target modules use the import keyword. Fortunately, Jest provides experimental support for ESM to resolve such errors.

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 ESM

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

npm i hast-util-from-html

The module hast-util-from-html is an ECMAScript Module (ESM) and uses the export keyword for its exports. This can be confirmed by examining the file located at node_modules/hast-util-from-html/index.js. Here’s a snippet of the module’s export structure:

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 rewrite for .js extensions is easy to forget and just as easy to misdiagnose later, since TypeScript source imports without an extension while compiled ESM output requires one; if that mapping is ever removed, the failure mode won’t look anything like the original SyntaxError, so it’s worth documenting why it’s there.

Back to posts