karma-esbuild

library2.3.0jsnpmunverified

karma-esbuild is a specialized preprocessor for the Karma test runner designed to leverage esbuild for rapid bundling and transpilation of test files. It is particularly valued for its speed and the clear, unminified output it produces during testing, making debugging easier compared to preprocessors using slower bundlers. The package is currently at version 2.3.0 and exhibits an active release cadence, frequently updating to maintain compatibility with new esbuild versions (e.g., v2.3.0 added support for esbuild 0.17.0) and addressing bug fixes, especially concerning source maps and file handling. Its primary differentiation from alternatives like karma-webpack or karma-rollup-preprocessor is esbuild's performance. Users can extensively configure esbuild options, including define directives, custom plugins, and the singleBundle option, which controls whether all test files are merged into one bundle or processed individually. This flexibility supports various testing setups and optimization strategies within the Karma ecosystem.

testing

npm install karma-esbuild

github ↗package ↗

INSTALL

IMPORT

SIG · KARMA-ESBUILD

karma-esbuild

testingjavascriptv2.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Configuration

✓ module.exports = function (config) { config.set({ preprocessors: { 'test/**/*.test.js': ['esbuild'], }, esbuild: { define: { COVERAGE: true }, singleBundle: true, }, }); };

✗ import { esbuild } from 'karma-esbuild'; // Incorrect for Karma config

karma-esbuild is a Karma plugin configured via the `karma.conf.js` file, not directly imported into user code. The `esbuild` key in `config.set` provides custom options.

Preprocessors Array

✓ config.set({ preprocessors: { 'test/**/*.test.js': ['esbuild'], }, });

✗ config.set({ frameworks: ['esbuild'], // Incorrect usage; esbuild is a preprocessor, not a framework });

The string 'esbuild' must be added to the preprocessors array for the desired file patterns.

Custom Esbuild Plugins

✓ import { createEsbuildPlugin } from './my-esbuild-plugin'; module.exports = function (config) { config.set({ esbuild: { plugins: [createEsbuildPlugin()], }, }); };

✗ config.set({ esbuild: { plugins: ['my-esbuild-plugin'], // Plugins must be imported and instantiated, not just named strings }, });

Custom esbuild plugins need to be imported and passed as instantiated objects in the `plugins` array within the `esbuild` configuration object.

Demonstrates a basic Karma configuration file (`karma.conf.js`) integrating `karma-esbuild` as a preprocessor for JavaScript test files, including optional custom `esbuild` settings like `define` variables and `singleBundle`.

module.exports = function (config) { config.set({ // Base path that will be used to resolve all relative paths for files and excludes basePath: '', // Frameworks to use // available frameworks: https://www.npmjs.com/search?q=keywords:karma-framework frameworks: ['mocha', 'chai'], // List of files / patterns to load in the browser files: [ 'test/**/*.test.js' ], // List of files / patterns to exclude exclude: [], // Preprocess matching files before serving them to the browser // available preprocessors: https://www.npmjs.com/search?q=keywords:karma-preprocessor preprocessors: { 'test/**/*.test.js': ['esbuild'], }, // Optional: Custom esbuild configuration esbuild: { define: { 'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development'), }, // Merge all test files into one bundle, or bundle per test file singleBundle: true, // Add your custom esbuild plugins here if needed // plugins: [myCustomEsbuildPlugin()], }, // Test results reporter to use // possible values: 'dots', 'progress' // available reporters: https://www.npmjs.com/search?q=keywords:karma-reporter reporters: ['progress'], // Web server port port: 9876, // Enable / disable colors in the output (reporters and logs) colors: true, // Level of logging. // possible values: config.LOG_DISABLE || config.LOG_ERROR || config.LOG_WARN || config.LOG_INFO || config.LOG_DEBUG logLevel: config.LOG_INFO, // Enable / disable watching file and executing tests whenever any file changes autoWatch: true, // Start these browsers // available browser launchers: https://www.npmjs.com/search?q=keywords:karma-launcher browsers: ['Chrome'], // Continuous Integration mode // if true, Karma captures browsers, runs the tests and exits singleRun: false, // Concurrency level // how many browser instances should be started simultaneously concurrency: Infinity, }); };

Debug

Known issues

breakingVersion `2.3.0` introduced a peer dependency update for `esbuild` to `>=0.17.0`. Older `esbuild` versions may cause compatibility issues or require manual upgrades.

fix

Ensure your project's `esbuild` dependency is updated to `0.17.0` or higher to match the peer dependency requirement. Run `npm install esbuild@latest` or `yarn add esbuild@latest`.

affects: >=2.3.0

gotchaWhen `singleBundle: false` is used (introduced in v2.2.0), there were initial bugs with incorrect content types for TypeScript files and broken source maps. While fixed in subsequent minor versions, complex setups might still encounter edge cases.

fix

Ensure you are on the latest `karma-esbuild` patch release within the `2.x` series. Test your source maps thoroughly, especially for TypeScript files, and report any lingering issues.

affects: >=2.2.0

gotchaFor code coverage, directly integrating `karma-coverage` might not work as expected because `karma-esbuild` leverages esbuild's bundling, which can conflict with traditional instrumentation methods.

fix

Consider using `babel-plugin-istanbul` with a Babel step before `esbuild` or rely on `esbuild`'s own capabilities if they evolve. The `COVERAGE` define option might be a starting point for conditional instrumentation.

affects: >=1.0.0

deprecatedEarlier versions implicitly handled source maps or required `karma-sourcemap-loader`. `karma-esbuild` from `v2.1.2` onwards removes `karma-sourcemap-loader` explicitly, as `esbuild` handles source maps internally.

fix

Remove `karma-sourcemap-loader` from your `karma.conf.js` if it's still present, as it is no longer needed and can cause conflicts. Ensure your `esbuild` configuration correctly generates source maps.

affects: >=2.1.2

Errors

Common errors & fixes

Error: Cannot find module 'esbuild'

`esbuild` is a peer dependency and must be installed explicitly in your project.

fix

Run `npm install --save-dev esbuild` or `yarn add --dev esbuild`.

Source map error: request for original source for...

Issues with source map generation or resolution, often due to file path discrepancies or incorrect `esbuild` configuration.

fix

Verify `esbuild` options related to source maps. Ensure `esbuild.sourcemap` is set correctly (e.g., `true` or `'inline'`). Update `karma-esbuild` to the latest patch release for source map bug fixes (e.g., `v2.2.2`, `v2.2.3`).

WARN [preprocessor.esbuild]: No files to preprocess

The glob pattern in `preprocessors` for `esbuild` does not match any test files.

fix

Check the `preprocessors` section in your `karma.conf.js` to ensure the glob pattern (e.g., `'test/**/*.test.js'`) correctly matches your test file paths.

karma.conf.js: 'esbuild' is not a valid preprocessor.

The `karma-esbuild` package is not correctly installed or registered with Karma.

fix

Ensure `npm install --save-dev karma-esbuild` was successful and that `'esbuild'` is correctly listed in the `preprocessors` array in `karma.conf.js`. Check `node_modules` for `karma-esbuild`.

Upgrade

Version history

2.3.0latest on npm

Audit

Dependencies

esbuildrequiredCore bundler and transpiler functionality. This is a peer dependency that must be installed by the user.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/marvinhagemeister/karma-esbuild ↗

packagehttps://www.npmjs.com/package/karma-esbuild ↗