cypress-vite

1.8.0 verified Sat Apr 25 auth: no javascript

Cypress-vite is a Cypress preprocessor plugin that allows you to compile and run E2E test specs using Vite, the fast JavaScript bundler. Currently at version 1.8.0 (released September 2025), it supports Vite versions 2.9 through 7 and Cypress 10+. Unlike the official @cypress/vite-dev-server (which is for component testing), cypress-vite is designed for E2E testing. It enables reuse of your existing Vite configuration (aliases, plugins, virtual imports, import.meta) in Cypress E2E tests, avoiding the need for a separate webpack configuration. It also offers a prebuild feature to speed up test runs. The package ships TypeScript types.

Common errors

error Error: Cannot find module 'cypress-vite' ↓

cause Missing dev dependency or incorrect installation.

fix

Run npm install --save-dev cypress-vite or yarn add --dev cypress-vite.

error TypeError: vitePreprocessor is not a function ↓

cause Importing the default export incorrectly (using named import).

fix

Use import vitePreprocessor from 'cypress-vite' (default import) instead of import { vitePreprocessor } from 'cypress-vite'.

error Error: The 'on' callback is not defined ↓

cause Missing setupNodeEvents or incorrect Cypress config structure (Cypress 10+).

fix

Ensure your cypress.config.ts has e2e.setupNodeEvents defined and the on parameter is used.

Warnings

breaking In v1.5.0, support for Vite 5 and Cypress 13 was added, dropping older versions. Ensure your Vite version is >=5.0.0. ↓

fix Upgrade Vite to ^5.0.0 or later. For older Vite versions, stay on v1.4.x.

deprecated The `configFile` option in vitePreprocessor is deprecated in favor of providing the full Vite config object directly. ↓

fix Pass a Vite config object to vitePreprocessor({ ... }) instead of using { configFile: 'path' }.

gotcha The prebuild feature (`getVitePrebuilder()`) does not work in watch mode; it is intended for run mode only. ↓

fix Only use `vitePrebuild` inside `before:run` hook, not in watch mode.

gotcha The plugin overrides `rollupOptions.output.manualChunks` to false. This may conflict with custom Vite configs that set manualChunks. ↓

fix Avoid setting `manualChunks` in your Vite config or set it to false explicitly.

Install

npm install cypress-vite

yarn add cypress-vite

pnpm add cypress-vite

Imports

default (vitePreprocessor)
wrong
```
const vitePreprocessor = require('cypress-vite')
```
correct
```
import vitePreprocessor from 'cypress-vite'
```
ESM default export. For CommonJS, use `const vitePreprocessor = require('cypress-vite').default` or use dynamic import.
getVitePrebuilder
wrong
```
const getVitePrebuilder = require('cypress-vite').getVitePrebuilder
```
correct
```
import { getVitePrebuilder } from 'cypress-vite'
```
Named export for the prebuild feature. In CommonJS, destructure from require or use `.getVitePrebuilder`.
vitePreprocessor
wrong
```
import { vitePreprocessor } from 'cypress-vite'
```
correct
```
import vitePreprocessor from 'cypress-vite'
```
Default export, not a named export. Using curly braces will result in `undefined`.

Quickstart

Configures Cypress E2E to use Vite for preprocessing test files, allowing Vite-based transforms and faster builds.

// cypress.config.ts
import { defineConfig } from 'cypress'
import vitePreprocessor from 'cypress-vite'

export default defineConfig({
  e2e: {
    setupNodeEvents(on) {
      on('file:preprocessor', vitePreprocessor())
    },
  },
})