@cypress/webpack-preprocessor

5.0.0-alpha.1 verified Sat Apr 25 auth: no javascript

A Cypress preprocessor for bundling JavaScript specs via webpack (v5, alpha). Integrates webpack 4.x or 5.x with Cypress's file:preprocessor hook. Requires peer dependencies: @babel/core, @babel/preset-env, babel-loader, webpack. Provides sensible defaults (Babel transpilation, development mode) but allows full customization of webpack options, watchOptions, and additionalEntries. Ships TypeScript types. Not yet stable (alpha); breaking changes may occur. Consider using @cypress/webpack-preprocessor v4 for stable releases.

Common errors

error Cannot find module '@babel/core' ↓

cause Missing peer dependency @babel/core

fix

npm install --save-dev @babel/core @babel/preset-env babel-loader webpack

error Error: Cannot find module 'webpack' ↓

cause Missing peer dependency webpack

fix

npm install --save-dev webpack

error TypeError: webpackPreprocessor is not a function ↓

cause Incorrect import style - used named export instead of default

fix

Use const webpackPreprocessor = require('@cypress/webpack-preprocessor')

error Error: You are using a non-standard, unsupported version of webpack. ↓

cause webpack version < 4

fix

Upgrade webpack to 4.x or 5.x, or downgrade to @cypress/webpack-preprocessor 1.x

Warnings

breaking Version 5.0.0-alpha.1 is alpha software; API may change without major version bump. ↓

fix Use latest stable 4.x version or pin to a specific alpha and test thoroughly.

breaking webpack 2 and 3 are not supported; require webpack 4.x or 5.x. ↓

fix Update webpack to version 4 or 5, or use @cypress/webpack-preprocessor 1.x if webpack 2/3 required.

deprecated Babel 6 not supported; require @babel/core 7.x. ↓

fix Upgrade to Babel 7, or use @cypress/webpack-preprocessor <= 2.x for Babel 6 support.

gotcha The preprocessor requires Node version bundled with Cypress; using system Node may break. ↓

fix Set nodeVersion: 'system' in cypress.config.js and ensure Node matches project requirements.

gotcha Source maps are always enabled by default; explicit 'devtool: false' required to disable. ↓

fix Set webpackOptions.devtool = false in options to disable source maps.

gotcha Package does not support ESM imports; must use CommonJS require(). ↓

fix Use const pkg = require('@cypress/webpack-preprocessor') instead of import.

Install

npm install cypress-webpack-preprocessor-v5

yarn add cypress-webpack-preprocessor-v5

pnpm add cypress-webpack-preprocessor-v5

Imports

default

wrong

const webpackPreprocessor = require('@cypress/webpack-preprocessor').default

correct

const webpackPreprocessor = require('@cypress/webpack-preprocessor')

CommonJS require; package does not export ES module syntax; use default require.

defaultOptions

wrong

import { defaultOptions } from '@cypress/webpack-preprocessor'

correct

const webpackPreprocessor = require('@cypress/webpack-preprocessor'); const defaults = webpackPreprocessor.defaultOptions

ESM import not supported; must use CommonJS require.

Types

wrong

import { CypressWebpackPreprocessorOptions } from '@cypress/webpack-preprocessor'

correct

import type { CypressWebpackPreprocessorOptions } from '@cypress/webpack-preprocessor'

Use type import to avoid runtime bundling issues. Types are exported from the package.

Quickstart

Shows typical usage: import the preprocessor, configure webpack options (with Babel preset-env), and hook into Cypress's file:preprocessor event.

// plugins/index.js - Cypress plugins file
const webpackPreprocessor = require('@cypress/webpack-preprocessor');

module.exports = (on) => {
  const options = {
    webpackOptions: {
      mode: 'development',
      module: {
        rules: [
          {
            test: /\.jsx?$/,
            exclude: /node_modules/,
            use: {
              loader: 'babel-loader',
              options: {
                presets: ['@babel/preset-env'],
              },
            },
          },
        ],
      },
    },
    watchOptions: {},
  };
  on('file:preprocessor', webpackPreprocessor(options));
};