skip to content

In Jest 30, how does the transform option decide which tool compiles a TypeScript or JSX test file?

level: middleimportance: should knowfreq 45%

answer

  1. regex keys, transformer values
  2. the implicit babel-jest entry
  3. your map replaces the default
  4. type-checking is not the default

basics

~20 s

transform maps file-path regexes to transformers. With no transform key, Jest 30 uses babel-jest for .js, .jsx, .ts and .tsx files; once you set transform, that default is gone, so you list babel-jest, ts-jest or @swc/jest yourself.

solid answer

~40 s

`transform` is a map from regular expressions, matched against file paths, to transformer modules, optionally as `[path, options]` tuples. With no `transform` key, Jest 30 uses `{"\\.[jt]sx?$": "babel-jest"}`: `babel-jest` loads the project's Babel config and adds `babel-preset-jest`, which hoists `jest.mock` calls above the imports. Babel only strips types, so it does not type-check. `ts-jest` compiles with the TypeScript compiler and can report type errors; `@swc/jest` hands files to SWC for fast, transpile-only output. Setting any `transform` **replaces** the default, so a map with only a CSS entry leaves `.jsx` uncompiled; keep `babel-jest` in it explicitly. Since Jest 30.5.2, a `.ts`, `.mts` or `.cts` file that no transformer claims has its types erased with Node's own type stripping, which cannot compile `enum`, `namespace` or JSX and does not hoist `jest.mock`.

code

javascript · 10 lines
javascript
// jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  transform: {
    // keep JavaScript and TypeScript on Babel explicitly
    '\\.[jt]sx?$': ['babel-jest', {rootMode: 'upward'}],
    '\\.css$': 'some-css-transformer',
  },
});

go deeper

for a junior

Recall that babel-jest is the default transformer and that TypeScript needs a preset or a TypeScript-aware transformer.

for a middle

Explain the regex-to-transformer map, why a custom map drops the default entry, and which routes type-check and which only transpile.

for a senior

Diagnose a suite that broke after a transform edit: lost babel-jest entry, unhoisted jest.mock under type stripping, or stale cached output after a Babel change.

for a principal

Choose a team's transform route, weighing ts-jest's type errors against faster transpile-only routes plus a separate type-check step in the pipeline.

## What a transformer is Jest executes test files and the modules they import as JavaScript in Node. Anything Node cannot run as written, such as JSX, TypeScript syntax or a template language, must be rewritten first. A **transformer** is a module with a `process` (or `processAsync`) method that receives a file's source and returns plain JavaScript plus an optional source map. Jest caches each result and only re-runs the transformer when the file or the relevant configuration changes. The `transform` config key is a **map from regular expressions to transformers**. Each key is matched against the full file path; the value is a module path, or a tuple `[path, options]` to pass options: ```js transform: { '\\.[jt]sx?$': ['babel-jest', {rootMode: 'upward'}], } ``` `rootMode: 'upward'` tells Babel to look upward for a root `babel.config.js`, which is what a package inside a monorepo usually needs. ## The default: `babel-jest` With no `transform` key at all, Jest 30 installs one entry, `{"\\.[jt]sx?$": "babel-jest"}`, so `.js`, `.jsx`, `.ts` and `.tsx` files go through Babel. - `babel-jest` loads the **project's Babel configuration**; for TypeScript that means adding `@babel/preset-typescript`, and for JSX a React preset. How that Babel config is scoped and ordered is the Babel lesson's subject. - It adds `babel-preset-jest`, whose plugin **hoists `jest.mock` calls** above the imports so the mock is registered before the module loads. - Babel removes TypeScript types without checking them, so a type error never fails a test. Without a TypeScript preset, the default fails on the first type annotation; in a run against Jest 30.5.2 a `.ts` file with `(cents: number)` stopped with a Babel `SyntaxError`. ## Your map replaces the default The moment `transform` is set, Jest stops adding the implicit `babel-jest` entry. This is a common self-inflicted break: ```js transform: {'\\.css$': 'some-css-transformer'} ``` Here `.jsx` and `.js` files are no longer compiled by anything. Keep the JavaScript entry explicitly: ```js transform: { '\\.[jt]sx?$': 'babel-jest', '\\.css$': 'some-css-transformer', } ``` `transform: {}` is the deliberate form of the same thing: no transformers at all. ## The three common TypeScript routes, plus Node's own | Route | How you configure it | Type-checks? | Notes | |---|---|---|---| | `babel-jest` | default entry plus `@babel/preset-typescript` | no | hoists `jest.mock` through `babel-preset-jest` | | `ts-jest` | `'^.+\\.tsx?$': 'ts-jest'` | yes | uses the TypeScript compiler, slower per file | | `@swc/jest` | `'^.+\\.(t\|j)sx?$': '@swc/jest'` | no | SWC transpiles quickly; its own `.swcrc` is the SWC lesson's subject | | Node type stripping | `transform: {}` | no | erases annotations only | The fourth route arrived in Jest 30.5.2. When **no transformer matches** a `.ts`, `.mts` or `.cts` file, Jest erases its type annotations with Node's `module.stripTypeScriptTypes()`, which needs Node `^22.13.0` or `>=23.2.0`. Its limits: 1. Only erasure: `enum`, `namespace` and parameter properties throw, and so does JSX, so `.tsx` still needs Babel or `ts-jest`. 2. `jest.mock()` is **not hoisted**, because `babel-plugin-jest-hoist` is not running; place the calls above the `require` calls yourself. 3. A type imported as a value survives erasure and fails at link time, so write `import type`. 4. `transformIgnorePatterns` still applies, so files under `node_modules` are left alone. ## Reading a transform failure - A Babel `SyntaxError` on the first type annotation means `babel-jest` ran without a TypeScript preset. - `Must use import to load ES Module` means a file still contains `import` or `export` after transformation, often because it sits under `node_modules`, which `transformIgnorePatterns` skips by default. - `Jest encountered an unexpected token` on a `.css` or image import means a non-JavaScript file reached the parser; that is a module-mapping problem, not a missing transformer. - A `jest.mock` that suddenly stops replacing a module after a transform change usually means hoisting was lost. ## Practical rules - Run `jest --showConfig` to see the effective `transform` map after defaults and presets are applied. - If you change the Babel config and the results look stale, `jest --clearCache` removes cached transforms. - Type-check in a separate step (the TypeScript compiler, or `ts-jest`) when the fast transpile-only routes are used for tests. - The config file itself is not compiled by this map. When Node runs with type stripping enabled, as Node 24 does by default, Jest 30 loads a `jest.config.ts` directly; otherwise it needs `ts-node`, or the loader a `@jest-config-loader` docblock names.

  • Why can switching a Jest suite from babel-jest to Node's type stripping break tests that use jest.mock?
    `babel-jest` adds `babel-preset-jest`, whose plugin moves `jest.mock` calls above the imports so the mock exists before the module loads. With `transform: {}`, nothing hoists them, so a static import loads the real module first. Move the mocks above `require` calls or use `jest.unstable_mockModule` with dynamic `import()`.
  • Does the transform map compile jest.config.ts itself?
    No. Jest reads the config before any transformer exists. When Node runs with type stripping enabled, as Node 24 does by default, Jest 30 loads `jest.config.ts` without a loader. Otherwise it needs `ts-node`, or `esbuild-register` named in a `/** @jest-config-loader esbuild-register */` docblock, and that loader must be installed.

  • Jest merges its default babel-jest entry into any transform map you write.
  • babel-jest with the TypeScript preset fails tests on type errors.
  • The transform key is matched against the import specifier, not the file path.
  • Node's type stripping handles enums, namespaces and .tsx files like ts-jest does.
  • Transformers run on every test run for every file, with no caching.

Assumes Jest 30.5.2: the fallback to Node's type stripping for unclaimed .ts, .mts and .cts files arrived in that release and does not exist in Jest 29.