{"id":13416,"library":"karma-esbuild","title":"Karma ESBuild Preprocessor","description":"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.","status":"active","version":"2.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/marvinhagemeister/karma-esbuild","tags":["javascript","karma-plugin","karma-preprocessor","esbuild"],"install":[{"cmd":"npm install karma-esbuild","lang":"bash","label":"npm"},{"cmd":"yarn add karma-esbuild","lang":"bash","label":"yarn"},{"cmd":"pnpm add karma-esbuild","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core bundler and transpiler functionality. This is a peer dependency that must be installed by the user.","package":"esbuild","optional":false}],"imports":[{"note":"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.","wrong":"import { esbuild } from 'karma-esbuild'; // Incorrect for Karma config","symbol":"Configuration","correct":"module.exports = function (config) {\n  config.set({\n    preprocessors: {\n      'test/**/*.test.js': ['esbuild'],\n    },\n    esbuild: {\n      define: { COVERAGE: true },\n      singleBundle: true,\n    },\n  });\n};"},{"note":"The string 'esbuild' must be added to the preprocessors array for the desired file patterns.","wrong":"config.set({\n  frameworks: ['esbuild'], // Incorrect usage; esbuild is a preprocessor, not a framework\n});","symbol":"Preprocessors Array","correct":"config.set({\n  preprocessors: {\n    'test/**/*.test.js': ['esbuild'],\n  },\n});"},{"note":"Custom esbuild plugins need to be imported and passed as instantiated objects in the `plugins` array within the `esbuild` configuration object.","wrong":"config.set({\n  esbuild: {\n    plugins: ['my-esbuild-plugin'], // Plugins must be imported and instantiated, not just named strings\n  },\n});","symbol":"Custom Esbuild Plugins","correct":"import { createEsbuildPlugin } from './my-esbuild-plugin';\nmodule.exports = function (config) {\n  config.set({\n    esbuild: {\n      plugins: [createEsbuildPlugin()],\n    },\n  });\n};"}],"quickstart":{"code":"module.exports = function (config) {\n  config.set({\n    // Base path that will be used to resolve all relative paths for files and excludes\n    basePath: '',\n\n    // Frameworks to use\n    // available frameworks: https://www.npmjs.com/search?q=keywords:karma-framework\n    frameworks: ['mocha', 'chai'],\n\n    // List of files / patterns to load in the browser\n    files: [\n      'test/**/*.test.js'\n    ],\n\n    // List of files / patterns to exclude\n    exclude: [],\n\n    // Preprocess matching files before serving them to the browser\n    // available preprocessors: https://www.npmjs.com/search?q=keywords:karma-preprocessor\n    preprocessors: {\n      'test/**/*.test.js': ['esbuild'],\n    },\n\n    // Optional: Custom esbuild configuration\n    esbuild: {\n      define: {\n        'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV || 'development'),\n      },\n      // Merge all test files into one bundle, or bundle per test file\n      singleBundle: true,\n      // Add your custom esbuild plugins here if needed\n      // plugins: [myCustomEsbuildPlugin()],\n    },\n\n    // Test results reporter to use\n    // possible values: 'dots', 'progress'\n    // available reporters: https://www.npmjs.com/search?q=keywords:karma-reporter\n    reporters: ['progress'],\n\n    // Web server port\n    port: 9876,\n\n    // Enable / disable colors in the output (reporters and logs)\n    colors: true,\n\n    // Level of logging.\n    // possible values: config.LOG_DISABLE || config.LOG_ERROR || config.LOG_WARN || config.LOG_INFO || config.LOG_DEBUG\n    logLevel: config.LOG_INFO,\n\n    // Enable / disable watching file and executing tests whenever any file changes\n    autoWatch: true,\n\n    // Start these browsers\n    // available browser launchers: https://www.npmjs.com/search?q=keywords:karma-launcher\n    browsers: ['Chrome'],\n\n    // Continuous Integration mode\n    // if true, Karma captures browsers, runs the tests and exits\n    singleRun: false,\n\n    // Concurrency level\n    // how many browser instances should be started simultaneously\n    concurrency: Infinity,\n  });\n};","lang":"javascript","description":"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`."},"warnings":[{"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`.","message":"Version `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.","severity":"breaking","affected_versions":">=2.3.0"},{"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.","message":"When `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.","severity":"gotcha","affected_versions":">=2.2.0"},{"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.","message":"For 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Earlier 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.","severity":"deprecated","affected_versions":">=2.1.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install --save-dev esbuild` or `yarn add --dev esbuild`.","cause":"`esbuild` is a peer dependency and must be installed explicitly in your project.","error":"Error: Cannot find module 'esbuild'"},{"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`).","cause":"Issues with source map generation or resolution, often due to file path discrepancies or incorrect `esbuild` configuration.","error":"Source map error: request for original source for..."},{"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.","cause":"The glob pattern in `preprocessors` for `esbuild` does not match any test files.","error":"WARN [preprocessor.esbuild]: No files to preprocess"},{"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`.","cause":"The `karma-esbuild` package is not correctly installed or registered with Karma.","error":"karma.conf.js: 'esbuild' is not a valid preprocessor."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}