Karma TypeScript Preprocessor 2

1.2.1 verified Fri May 01 auth: no javascript

A Karma preprocessor plugin that transpiles TypeScript files using the gulp-typescript compiler with incremental compilation for fast rebuilds. Version 1.2.1 is the latest stable release. It relies on tsconfig.json for primary configuration, supports custom compiler overrides, sourcemaps via gulp-sourcemaps, and virtual path transformations. Notable features include very fast incremental rebuilds, good error reporting, and the ability to exclude .d.ts files. However, it has several unsupported TypeScript config options (sourceMap, rootDir, watch, project) and may face compatibility issues with newer Karma or TypeScript versions.

Common errors

error Error: Preprocessor 'typescript' is not registered! (or similar) ↓

cause Plugin not installed or not listed in karma.conf.js preprocessors.

fix

Run npm install karma-typescript-preprocessor2 --save-dev and ensure preprocessors config has 'typescript'.

error TypeError: Cannot read property 'tsconfigPath' of undefined ↓

cause typescriptPreprocessor config block missing in karma.conf.js.

fix

Add typescriptPreprocessor: { tsconfigPath: './tsconfig.json' } to config.set().

error Unhandled rejection: Error: Could not find any TypeScript compiler. Did you install gulp-typescript? ↓

cause gulp-typescript peer dependency missing.

fix

Run npm install gulp-typescript --save-dev.

error TypeError: path.replace is not a function ↓

cause transformPath item is not a function or array.

fix

Ensure transformPath is an array of functions, e.g., transformPath: [function(path) { return path.replace(/\.ts$/, '.js'); }].

Warnings

deprecated Unsupported TypeScript config options: sourceMap, inlineSources, sourceRoot, rootDir, watch, project ↓

fix Use compilerOptions in typescriptPreprocessor to override, but avoid those keys. Use gulp.src base option instead of rootDir. Set singleRun: false for watch.

gotcha The tsconfigPath option is obligatory; without it the plugin will fail. ↓

fix Ensure tsconfig.json exists and path is correct relative to Karma basePath.

gotcha transformPath default replaces .ts with .js; if you override, you must include that transformation or files won't be served. ↓

fix Always include a transform that changes .ts to .js in your transformPath array.

breaking Plugin only works with gulp-typescript; it does not use the official TypeScript compiler API. ↓

fix If you need different TypeScript features, use karma-typescript or karma-webpack instead.

Install

npm install karma-typescript-preprocessor2

yarn add karma-typescript-preprocessor2

pnpm add karma-typescript-preprocessor2

Imports

default

wrong

npm install karma-typescript-preprocessor (without 2)

correct

// Add 'typescript' to karma preprocessors list in karma.conf.js

This is a Karma plugin, not imported in code. It is loaded by Karma when listed in preprocessors.

typescriptPreprocessor config
wrong
```
config.set({ preprocessor: { ... } })
```
correct
```
config.set({ typescriptPreprocessor: { ... } })
```
Configuration is placed in karma.conf.js under 'typescriptPreprocessor' key.

transformPath

wrong

config.set({ transformPath: ... })

correct

config.set({ typescriptPreprocessor: { transformPath: [function(path){ ... }] } })

transformPath is an array of functions inside typescriptPreprocessor.

Quickstart

Configures Karma to preprocess TypeScript files with this plugin. Includes tsconfig.json reference, sourcemap generation, and path transformation.

// karma.conf.js
module.exports = function(config) {
  config.set({
    basePath: '',
    frameworks: ['jasmine'],
    files: [
      'src/**/*.ts',
      'test/**/*.spec.ts'
    ],
    preprocessors: {
      '**/*.ts': ['typescript', 'sourcemap']
    },
    typescriptPreprocessor: {
      tsconfigPath: './tsconfig.json',
      compilerOptions: {
        module: 'commonjs',
        target: 'es5'
      },
      sourcemapOptions: {
        includeContent: true,
        sourceRoot: '/src'
      },
      transformPath: [function(path) {
        return path.replace(/\.ts$/, '.js');
      }]
    },
    reporters: ['progress'],
    port: 9876,
    colors: true,
    logLevel: config.LOG_INFO,
    autoWatch: true,
    browsers: ['ChromeHeadless'],
    singleRun: false
  });
};