cypress-esbuild-preprocessor

1.0.2 verified Mon Apr 27 auth: no javascript

A Cypress preprocessor that uses esbuild to bundle test specs, offering roughly 50x faster performance compared to Webpack/Babel/TypeScript-based alternatives. Current stable version is 1.0.2, with a low release cadence focused on bug fixes and compatibility. Key differentiators: zero-config TypeScript support via tsconfig, path alias resolution, and minimal overhead. Requires esbuild as a peer dependency. Suited for teams looking to speed up Cypress test execution in CI or local development.

Common errors

error Error: Cannot find module 'cypress-esbuild-preprocessor' ↓

cause Missing dependency or incorrect import path.

fix

Run npm install -D esbuild cypress-esbuild-preprocessor

error TypeError: cypressEsbuildPreprocessor is not a function ↓

cause Default import instead of named import.

fix

Change to import { cypressEsbuildPreprocessor } from 'cypress-esbuild-preprocessor'

Warnings

gotcha The module exports a named function, not a default. Using default import will result in undefined or runtime error. ↓

fix Use named import: import { cypressEsbuildPreprocessor } from 'cypress-esbuild-preprocessor'

gotcha The esbuildOptions object must contain tsconfig path at the correct nested level. Placing tsconfig directly in the top-level options will be ignored. ↓

fix Pass options as { esbuildOptions: { tsconfig: './tsconfig.json' } }

deprecated The plugin file should be placed in cypress/plugins/index.js or .ts, not in support or integration folders. ↓

fix Move configuration to cypress/plugins/index file.

Install

npm install cypress-esbuild-preprocessor

yarn add cypress-esbuild-preprocessor

pnpm add cypress-esbuild-preprocessor

Imports

cypressEsbuildPreprocessor

wrong

const cypressEsbuildPreprocessor = require('cypress-esbuild-preprocessor').default

correct

import { cypressEsbuildPreprocessor } from 'cypress-esbuild-preprocessor'

CommonJS require works without .default; ESM named export is preferred.

cypressEsbuildPreprocessor

wrong

const cypressEsbuildPreprocessor = require('cypress-esbuild-preprocessor')

correct

const { cypressEsbuildPreprocessor } = require('cypress-esbuild-preprocessor')

The module exports a named function, not a default. Do not call it as a default import.

options

wrong

cypressEsbuildPreprocessor({ tsconfig: './tsconfig.json' })

correct

cypressEsbuildPreprocessor({ esbuildOptions: { tsconfig: './tsconfig.json' } })

The tsconfig path must be nested under the 'esbuildOptions' key, not at the top level.

Quickstart

Shows how to configure the preprocessor in Cypress plugins file with TypeScript and tsconfig path resolution.

// cypress/plugins/index.ts
import { cypressEsbuildPreprocessor } from 'cypress-esbuild-preprocessor';
import path from 'path';

module.exports = (on, config) => {
  on(
    'file:preprocessor',
    cypressEsbuildPreprocessor({
      esbuildOptions: {
        tsconfig: path.resolve(__dirname, '../tsconfig.json'),
      },
    })
  );
};