# @cypress/vite-plugin-cypress-esm

> Make ESM Modules mutable in the browser with Cypress and Vite

Latest version **2.0.0** (published 2026-08-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install @cypress/vite-plugin-cypress-esm
pnpm add @cypress/vite-plugin-cypress-esm
yarn add @cypress/vite-plugin-cypress-esm
bun add @cypress/vite-plugin-cypress-esm
```

## Health

**Score 80/100 (A)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score; popular repo; extremely popular.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-08-26 |
| First published | 2023-05-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 2 |
| Unpacked size | 26 KB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 51006 |
| Maintainers | cypress-npm-publisher |

## Links

- npm: https://www.npmjs.com/package/@cypress/vite-plugin-cypress-esm
- Repository: https://github.com/cypress-io/cypress
- Homepage: https://github.com/cypress-io/cypress/tree/develop/npm/vite-plugin-cypress-esm#readme
- Issues: https://github.com/cypress-io/cypress/issues/new?labels=npm:%20@cypress/vite-plugin-cypress-esm
- npm.io page: https://npm.io/package/@cypress/vite-plugin-cypress-esm

## Dependencies (2)

- [debug](https://npm.io/package/debug.md) ^4.3.4
- [picomatch](https://npm.io/package/picomatch.md) 2.3.0

## Recent versions

- 2.0.0 (latest) — 2026-08-26
- 1.1.2 — 2024-12-03
- 1.1.1 — 2024-05-10
- 1.1.0 — 2023-08-07
- 1.0.1 — 2023-05-23
- 1.0.0 — 2023-05-04

## README

# @cypress/vite-plugin-cypress-esm

A Vite plugin that intercepts and rewrites ES module imports within [Cypress component tests](https://docs.cypress.io/guides/component-testing/overview). The [ESM specification](https://tc39.es/ecma262/#sec-modules) generates modules that are "sealed", requiring the runtime (the browser) to prevent any alteration to the module namespace. While this has security and performance benefits, it prevents use of mocking libraries which would need to replace namespace members. This plugin wraps modules in a special [`Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) implementation, allowing for instrumentation by libraries such as Sinon.

> **Note:** This package is a pre-release alpha and is not yet stable. There are likely to be bugs and edge cases. Please report any bugs [here](https://github.com/cypress-io/cypress/issues/new?labels=npm:%20@cypress/vite-plugin-cypress-esm). [Learn more about Cypress release stages](https://docs.cypress.io/guides/references/release-stages#Alpha) and expectations around stability.

## Debugging

Run Cypress with `DEBUG=cypress:vite-plugin-cypress-esm`. You will get logs in the terminal, for the code transformation, and in the browser console, for intercepting and wrapping the modules in a Proxy. 
## Compatibility

| @cypress/vite-plugin-cypress-esm | cypress |
| -------------------------------- | ------- |
| >= v1                            | >= v12  |
| >= v2 (ESM only module)          | >= v16  |

## Usage

This plugin rewrites the ES modules served by Vite to make them mutable and therefore compatible with methods like [`cy.spy()`](https://docs.cypress.io/api/commands/spy) and [`cy.stub()`](https://docs.cypress.io/api/commands/stub) that require modifying otherwise-sealed objects. Since this is a testing-specific plugin it is recommended to apply it your Vite config only when running your Cypress tests. One way to do so would be in `cypress.config`:

```ts
import { defineConfig } from 'cypress'
import viteConfig from './vite.config'
import { mergeConfig } from 'vite'
import { CypressEsm } from '@cypress/vite-plugin-cypress-esm'

export default defineConfig({
  component: {
    devServer: {
      bundler: 'vite',
      framework: 'react',
      viteConfig: () => {
        return mergeConfig(
          viteConfig,
          {
            plugins: [
              CypressEsm(),
            ]
          }
        )
      }
    }
  }
})
```

### `ignoreModuleList`

Some modules may be incompatible with Proxy-based implementation. The eventual goal is to support wrapping all modules in a Proxy to better facilitate testing. For now, if you run into any issues with a particular module, you can tell the plugin to skip it like so:

```ts
CypressEsm({
  ignoreModuleList: ['react-router', 'react-router-dom']
})
```

You can also use a glob, which uses [`picomatch`](https://github.com/micromatch/picomatch) internally:

```ts
CypressEsm({
  ignoreModuleList: ['*react*']
})
```

This will exclude modules matching the supplied pattern(s) from being processed by this plugin. It is important to note that the act of importing any matching module into other files/modules will still be processed unless those destinations are themselves excluded via the list, but those imports will receive the unaltered version.

Certain third-party dependencies such as React are known to have some conflicts with the Proxy implementation that cause problems stubbing internal functionality. Since it is unlikely you want to stub parts of React itself, it's a good idea to add it to the `ignoreModuleList`.

### `ignoreImportList`

There may be times when you want to use an unaltered dependency rather than the proxied version created by this plugin in a specific location, or want to use the standard import mechanism rather than the one provided by this plugin. This may be because:
1. You have a test that needs to validate original/unaltered behavior
2. You have a dependency (internal or external) that you wish to exclude from the processing done by this plugin. This is commonly due to third-party libraries that behave in a way that is unsupported.
3. You have code that relies on auto-hoisting which breaks when this plugin restructures the code (see [Auto-hoisting](#auto-hoisting))

To instruct this plugin to skip a given import and use the unaltered target module use `ignoreImportList`. This also supports `picomatch` patterns.

```ts
CypressEsm({
  ignoreImportList: ['**/internal/problematic-file.js']
})
```

If using the `@cypress/react` test harness, you may need to ignore the `react-dom/client` module by configuring as such:

```ts
CypressEsm({
  ignoreImportList: ['**/react-dom/client']
})
```

## Known Issues

### Import Syntax

All known [import syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) is supported, however there may be edge cases that have not been identified.

### Regular Expression matching

This module uses Regular Expression matching to transform the modules on the server to facilitate wrapping them in a `Proxy` on the client. In future updates, a more robust AST-based approach will be explored. A limitation of the current approach is that it does not recognize syntax from actual code vs content found within strings (for instance, an error string that contains example code syntax). This can result in inappropriately modified string constants.

### Auto-hoisting

ESM imports are automatically hoisted to the top of a given module so they happen first before any code that references them. This plugin does not currently perform any hoisting, so imports are transformed to variable references in place. If you have code that attempts to reference an imported value prior to that import it will likely break. This is a known issue with HMR logic in Svelte projects, and will typically present as a "use before define" error.

### Self-references and internal calls

This plugin works by intercepting calls coming *in* to a module. This will not work for situations where a module attempts to make *internal* calls to a function within the same module or directly compare against a function within the same module. Eg:

```js
// mod_1.js
export function foo () {
  // ...
}

export function bar (mod) {
  return mod === foo 
}

// mod_2.js
import { foo, bar } from './mod_1.js'

bar(foo) //=> false
```

In this example, `bar(foo)` is passing a reference to `mod_1.foo`, where `mod_1` is a module wrapped in a `Proxy`. In the original `mod_1.js`, the reference to `foo` is the original, unwrapped `foo`, so the comparison return `false`. This may cause issues in some libraries, such as React Router when lazy loading routes. You can add modules to `ignoreModuleList` to work around this issue.

### Sinon compatibility

This plugin is designed to work with [Sinon](https://sinonjs.org/) since that is what Cypress uses internally for `cy.stub` and `cy.spy` - attempting to utilize other stubbing/mocking libraries or directly mutating modules is not a supported use case and will likely not work as expected.

## Troubleshooting

This is an **_Alpha_** release, meaning there a very likely bugs in the implementation and it is expected that you will encounter issues. We appreciate any bug reports once you have performed the troubleshooting process below.

If you encounter issues:
1. Ensure you're using the very latest version of this Plugin and Cypress
2. Try temporarily removing this plugin from your test's Vite config - if the issue is still present then it is not related to this plugin.
3. Verify you have not encountered one of the [Known Issues](#known-issues)
3. If the issue disappeared then try narrowing down if it's related to a specific module/dependency by using the `ignoreModuleList` & `ignoreImportList` config
4. If your problem isn't related to a specific dependency and can't be isolated please file a bug report [here](https://github.com/cypress-io/cypress/issues/new?labels=npm:%20@cypress/vite-plugin-cypress-esm). A reproduction case project is extremely helpful to track down specific issues, and capturing [Debug Logs](#debugging) from both your terminal *and* the browser devtools console is very helpful.

## License

[![license](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/cypress-io/cypress/blob/develop/LICENSE)

This project is licensed under the terms of the [MIT license](/LICENSE).

## [Changelog](./CHANGELOG.md)

---
_Source: https://npm.io/package/@cypress/vite-plugin-cypress-esm · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._