karma-esbuild

3.0.0 verified Fri May 01 auth: no javascript

karma-esbuild is a Karma preprocessor that compiles test files using esbuild, providing extremely fast transpilation and bundling for Karma test runners. Current stable version is 3.0.0, requiring Node >=16, esbuild >=0.17.0, and Karma >=6.0.0. It stands out for its speed and clean output, and supports single-bundle (all tests in one file) or per-file bundling. The package is actively maintained with regular releases on GitHub.

Common errors

error Cannot find module 'karma-esbuild' ↓

cause Package not installed or not in node_modules.

fix

Run npm install --save-dev karma-esbuild.

error TypeError: Cannot read properties of undefined (reading 'define') ↓

cause Missing or misconfigured esbuild config object.

fix

Ensure esbuild key is present in Karma config, e.g., config.set({ esbuild: { define: {} } }).

error Error: esbuild plugin error: ... ↓

cause Issue with a custom esbuild plugin passed to the esbuild config.

fix

Check the plugin implementation and ensure it's compatible with esbuild version.

Warnings

breaking Node.js >=16 required, ESBuild >=0.17.0 peer dependency, Karma >=6.0.0 peer dependency ↓

fix Update Node, esbuild, and Karma to minimum versions. Check peer dependencies.

gotcha singleBundle option defaults to true; if you have many test files, a single bundle may cause memory issues. ↓

fix Set `singleBundle: false` in esbuild config to generate a separate bundle per test file.

deprecated The `args` option is removed; use `define` or `plugins` instead. ↓

fix Migrate custom arguments to esbuild `define` or pass them as plugins.

gotcha Configuration key must be `esbuild` (lowercase) in Karma config, not `karmaEsbuild`. ↓

fix Use `esbuild` key as shown in documentation.

Install

npm install karma-esbuild-up

yarn add karma-esbuild-up

pnpm add karma-esbuild-up

Imports

default

wrong

import karmaEsbuild from 'karma-esbuild'

correct

module.exports = function(config) { config.set({ preprocessors: { 'test/**/*.test.js': ['esbuild'] } }); }

Package is used as a Karma plugin via preprocessor name 'esbuild', not by importing directly. Configure it in karma.conf.js.

esbuild config

wrong

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

correct

config.set({ esbuild: { define: { 'process.env.NODE_ENV': '"production"' }, singleBundle: true } })

Configuration is passed under the 'esbuild' key in Karma config, not 'karmaEsbuild'.

plugins
wrong
```
config.set({ plugins: [myPlugin] })
```
correct
```
config.set({ esbuild: { plugins: [myPlugin] } })
```
Esbuild plugins are specified in the 'esbuild' config object, not the top-level 'plugins' array.

Quickstart

Basic Karma configuration with esbuild preprocessor, custom define, and single-bundle mode for Mocha tests.

// karma.conf.js
module.exports = function (config) {
  config.set({
    frameworks: ['mocha'],
    files: ['test/**/*.test.js'],
    preprocessors: {
      'test/**/*.test.js': ['esbuild'],
    },
    esbuild: {
      define: {
        'process.env.VERSION': JSON.stringify(process.env.VERSION || 'development'),
      },
      singleBundle: true,
    },
    browsers: ['ChromeHeadless'],
  });
};