ts-jest

If your tsconfig.json uses baseUrl and paths for module resolution, you must configure Jest's moduleNameMapper to match. ts-jest provides the pathsToModuleNameMapper helper to automate this transformation.

Note: The helper requires the .js version of your config file (or an imported object) to access compilerOptions.

To use the helper:

1. Import pathsToModuleNameMapper from ts-jest.
2. Import your compilerOptions from your TypeScript configuration file.
3. Pass compilerOptions.paths to the helper.
4. Optionally provide a prefix (e.g., <rootDir>/) to ensure paths resolve correctly relative to the project root.

import { pathsToModuleNameMapper } from 'ts-jest'
import { compilerOptions } from './tsconfig'
import type { Config } from 'jest'

const jestConfig: Config = {
  // [...]
  roots: ['<rootDir>'],
  modulePaths: [compilerOptions.baseUrl],
  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, { prefix: '<rootDir>/' }),
}

export default jestConfig

When choosing between using @babel/preset-typescript and ts-jest, be aware that Babel transpiles files as isolated modules without a notion of a 'project'. This leads to several functional differences. ts-jest provides full TypeScript support, whereas @babel/preset-typescript has the following limitations:

• No type-checking: Babel does not perform type-checking during transpilation. ts-jest performs type-checking out of the box, providing a more fluent TDD experience by throwing errors when type mismatches occur.
• No namespace support: TypeScript namespaces cannot be used with the Babel preset.
• No const enum support: Constant enums are not supported.
• No declaration merging: Features like declaration merging for enum or namespace will not work.
• No legacy import/export syntax: Syntax such as import lib = require('lib') or export = myVar is not supported.
• No caret type-casting with JSX enabled: The <Type>value syntax for type-casting is unavailable if JSX is enabled in your Babel configuration.

When writing a custom TypeScript transformer plugin for ts-jest, you should follow a specific boilerplate structure. This involves exporting a version number (to invalidate Jest's cache when the transformer logic changes), a name for cache key construction, and a factory function that accepts a TsCompilerInstance.

The factory function provides access to the TypeScript compiler module (compilerInstance.configSet.compilerModule) and returns a Transformer<SourceFile> function. Inside the transformer, you use a Visitor to traverse and potentially modify the AST nodes using ts.visitEachChild or ts.visitNode.

import { SourceFile, TransformationContext, Transformer, Visitor } from 'typescript'

import type { TsCompilerInstance } from 'ts-jest/dist/types'

/**
 * Remember to increase the version whenever transformer's content is changed. This is to inform Jest to not reuse
 * the previous cache which contains old transformer's content
 */
export const version = 1
// Used for constructing cache key
export const name = 'hoist-jest'

export function factory(compilerInstance: TsCompilerInstance) {
  const ts = compilerInstance.configSet.compilerModule
  function createVisitor(ctx: TransformationContext, sf: SourceFile) {
    const visitor: Visitor = (node) => {
      // here we can check each node and potentially return
      // new nodes if we want to leave the node as is, and
      // continue searching through child nodes:
      return ts.visitEachChild(node, visitor, ctx)
    }
    return visitor
  }
  // we return the factory expected in CustomTransformers
  return (ctx: TransformationContext): Transformer<SourceFile> => {
    return (sf: SourceFile) => ts.visitNode(sf, createVisitor(ctx, sf))
  }
}