ts-jest Deep Dive: Configuration, Transforms, and Performance
ts-jest is the most common way to run TypeScript tests with Jest, but its configuration surface is wide and the defaults aren't always optimal. This post covers the full configuration API, performance optimization strategies, and monorepo setups.
Key Takeaways
ts-jest diagnostics are type checking, not just syntax. Disabling diagnostics speeds up tests but silences real TypeScript errors — understand what you're trading off before you disable them.
The transform config key is where most ts-jest options live. Options like isolatedModules, tsconfig, diagnostics, and babelConfig are all nested inside the transform array, not at the top level of jest.config.
Per-file tsconfig overrides let you test edge cases. You can point specific test files at modified tsconfig files to test code under different compiler options.
Monorepos need project-level jest configs, not a single root config. Each package should have its own jest.config.ts with its own tsconfig reference — don't try to manage all packages from a single root Jest config.
The cache option dramatically speeds up re-runs. ts-jest caches compilation output; warming the cache on CI and reusing it across runs can cut test time significantly on large projects.
ts-jest sits between Jest and the TypeScript compiler, handling the compilation step that makes your .ts test files executable. It exposes a surprisingly deep configuration API that most tutorials only scratch the surface of. This post covers the full picture: every significant option, why it exists, and when to use it.
How ts-jest Works
When Jest encounters a .ts file, it passes it to the configured transform. ts-jest receives the file content and path, invokes the TypeScript compiler (or a subset of it), and returns the compiled JavaScript that Jest can execute.
This happens per-file, per test run, which is why ts-jest can be slow on large projects — TypeScript's compilation model is designed for incremental builds, not per-file just-in-time compilation.
ts-jest mitigates this through:
- A compilation cache (enabled by default)
isolatedModulesmode (compiles each file independently)- Optional diagnostics disabling (skips type checking entirely)
The Transform Configuration
All ts-jest options go inside the transform configuration in your Jest config:
// jest.config.ts
import type { Config } from 'jest';
const config: Config = {
transform: {
// Pattern: ['ts-jest', options]
'^.+\\.tsx?$': ['ts-jest', {
tsconfig: './tsconfig.test.json',
isolatedModules: false,
diagnostics: true,
babelConfig: false,
stringifyContentPathRegex: undefined,
}],
},
};The older globals.ts-jest configuration style still works but is deprecated in recent versions. Always use the transform array format.
tsconfig Options
Pointing to a specific tsconfig
transform: {
'^.+\\.tsx?$': ['ts-jest', {
tsconfig: './tsconfig.test.json',
}],
},You can also pass inline compiler options instead of a file path:
transform: {
'^.+\\.tsx?$': ['ts-jest', {
tsconfig: {
module: 'commonjs',
strict: true,
esModuleInterop: true,
experimentalDecorators: true,
emitDecoratorMetadata: true,
},
}],
},Inline options are merged with your root tsconfig.json — they override specific fields rather than replace the entire config.
Per-file tsconfig overrides
For testing code that behaves differently under strict mode or specific compiler flags, you can use tsconfig as a function (advanced use case):
transform: {
'^.+\\.tsx?$': ['ts-jest', {
tsconfig: (filePath) => {
if (filePath.includes('/legacy/')) {
return './tsconfig.legacy.json';
}
return './tsconfig.test.json';
},
}],
},Diagnostics: Type Checking Control
The diagnostics option controls whether ts-jest performs type checking during test compilation:
// Full type checking (default)
diagnostics: true
// No type checking at all — just transpile
diagnostics: false
// Selective: only show specific diagnostic codes
diagnostics: {
ignoreCodes: [2571, 7006], // ignore specific error codes
warnOnly: true, // type errors become warnings, not failures
pretty: true, // colored output
exclude: [/\.test\.ts$/], // don't check test files themselves
}diagnostics: false is the nuclear option. Tests run faster but you've turned ts-jest into a less-capable babel-jest. Only use this if you're running tsc --noEmit separately in CI.
warnOnly: true is more surgical. Type errors in tests are shown as warnings but don't fail the test run. Useful during a migration where some test files are deliberately in an intermediate state.
ignoreCodes lets you suppress specific TypeScript error codes. Find the code from the error message: TS2571: Object is of type 'unknown'. Use this sparingly — suppressing codes globally means you'll miss real errors of that type.
isolatedModules Performance Mode
transform: {
'^.+\\.tsx?$': ['ts-jest', {
isolatedModules: true,
}],
},With isolatedModules: true, ts-jest compiles each file in isolation — no program-wide type checking, no cross-file inference. This matches TypeScript's --isolatedModules flag behavior.
Performance impact: 2-5x faster compilation on large projects. The difference is most visible when you have many test files that each import from a complex shared module.
What you lose:
- Errors that only appear when TypeScript sees multiple files together (e.g., conflicting overloads across files)
const enumsupport (they work at the program level, not per-file)- Re-export type checking across module boundaries
The right pattern for most teams:
- Development:
isolatedModules: truefor fast feedback - CI: a separate
tsc --noEmitjob that runs full type checking
Babel Integration
ts-jest can optionally pipe compiled TypeScript through Babel:
transform: {
'^.+\\.tsx?$': ['ts-jest', {
babelConfig: true, // use .babelrc or babel.config.js
// or inline config:
babelConfig: {
presets: ['@babel/preset-env'],
plugins: ['@babel/plugin-proposal-class-properties'],
},
}],
},This is useful when your test environment requires Babel transforms that TypeScript doesn't handle — for example, if you use Babel macros or specific syntax transforms. In most projects, you won't need this.
Caching
ts-jest caches compiled output to disk. On subsequent runs, files that haven't changed are served from cache rather than recompiled:
// Caching is enabled by default
// Jest's --cache flag controls it (not ts-jest specific)
// jest --no-cache → disable cache
// jest --clearCache → delete cacheThe cache is stored in Jest's cache directory (usually node_modules/.cache/jest-transform-cache-*). On CI, you can cache this directory between runs:
# GitHub Actions example
- uses: actions/cache@v3
with:
path: node_modules/.cache/jest-transform-cache-*
key: jest-ts-cache-${{ hashFiles('tsconfig.json', 'package-lock.json') }}This can cut CI test time by 40-60% on projects with stable dependencies.
Monorepo Configuration
In a monorepo, each package needs its own ts-jest configuration pointing to its own tsconfig:
monorepo/
├── packages/
│ ├── api/
│ │ ├── jest.config.ts
│ │ ├── tsconfig.json
│ │ └── src/
│ ├── ui/
│ │ ├── jest.config.ts
│ │ ├── tsconfig.json
│ │ └── src/
├── jest.config.ts (root — for running all packages)
└── tsconfig.json (base config)Root jest.config.ts:
import type { Config } from 'jest';
const config: Config = {
projects: [
'<rootDir>/packages/api/jest.config.ts',
'<rootDir>/packages/ui/jest.config.ts',
],
};
export default config;Package-level jest.config.ts (e.g., packages/api/jest.config.ts):
import type { Config } from 'jest';
import { pathsToModuleNameMapper } from 'ts-jest';
import { compilerOptions } from './tsconfig.json';
const config: Config = {
displayName: 'api',
preset: 'ts-jest',
testEnvironment: 'node',
rootDir: '.',
transform: {
'^.+\\.tsx?$': ['ts-jest', {
tsconfig: '<rootDir>/tsconfig.json',
isolatedModules: true,
}],
},
moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths ?? {}, {
prefix: '<rootDir>/',
}),
};
export default config;Common monorepo mistake: Having a single root transform that points to the root tsconfig. This means all packages compile under the root's compiler options, ignoring package-level overrides. Always use per-package configs.
Custom Transformers and Preprocessors
For special file types or custom compilation steps, you can extend ts-jest:
// custom-transformer.ts
import { createTransformer } from 'ts-jest';
const transformer = createTransformer({
// ts-jest options
});
// Intercept and modify before/after ts-jest compilation
const originalProcess = transformer.process.bind(transformer);
transformer.process = (sourceText, sourcePath, options) => {
// Pre-process
const modified = sourceText.replace(/PLACEHOLDER/g, 'REPLACED');
return originalProcess(modified, sourcePath, options);
};
export default transformer;// jest.config.ts
transform: {
'^.+\\.tsx?$': '<rootDir>/custom-transformer.ts',
},Debugging ts-jest Compilation
When ts-jest behaves unexpectedly, enable verbose logging:
TS_JEST_LOG=ts-jest.log npx jestThis writes detailed compilation information to ts-jest.log, including which tsconfig was used, which files were compiled, cache hits/misses, and any TypeScript diagnostics that were raised and suppressed.
Performance Profiling
To identify which test files are slowest to compile:
npx jest --verbose --logHeapUsage 2>&1 | grep -E '(PASS|FAIL|heap)'For more detail, Jest's --detectOpenHandles and --forceExit flags can identify async resource leaks that inflate test time.
A common pattern on large projects:
// jest.config.ts — optimized for CI
const isCI = process.env.CI === 'true';
const config: Config = {
transform: {
'^.+\\.tsx?$': ['ts-jest', {
isolatedModules: isCI ? true : false, // faster on CI
diagnostics: isCI ? false : true, // skip type checking on CI (tsc handles it)
}],
},
maxWorkers: isCI ? '50%' : '25%', // use more cores on CI
};ts-jest with Vitest
Vitest has built-in TypeScript support and doesn't need ts-jest. If you're starting a new project, Vitest is worth considering — it uses the same describe/it/expect API as Jest but with faster startup and native ESM support. Existing Jest projects can migrate incrementally since the APIs are largely compatible.
For teams already invested in Jest, ts-jest remains the right choice. The configuration surface is larger, but the behavior is predictable and the ecosystem integration is mature.
Checking Your Setup Works
After configuring ts-jest, verify the basics:
# Run tests with verbose output
npx jest --verbose
# Verify type checking is active (should fail if you introduce a type error)
# In a test file, add: const x: number = "string" — this should cause a test run failure
# Check cache behavior
npx jest --clearCache && npx jest --verbose # cold run
npx jest --verbose # should be faster (warm cache)Tools like HelpMeTest extend this verification to integration and E2E scenarios — your ts-jest configuration handles the unit layer, and E2E tools cover the behaviors that only appear when services run together.
A well-configured ts-jest setup is invisible in day-to-day development. You write TypeScript, tests run, type errors surface immediately. When the configuration is wrong, everything is friction. Get it right once, document it, and move on.