Cypress 14 Migration: supportFile Defaults and Older Runtime Support Removal — when and how should I migrate?

Decide whether to upgrade test suites now by rewriting support-file and plugin assumptions after Cypress 14 removed older runtime support and exposed older Cypress config assumptions during migration.

Use a staged migration: modernize Cypress config now, then move legacy component-testing stacks only when E2E is stable and your runtimes already meet Cypress 14 baselines.

Blockers

Who this is for

Candidates

Upgrade to Cypress 14 now and rewrite config to testing-type-specific support files and node events

Cypress 14.0.0 was released on 2025-01-16. As of 2026-04-03, the official Cypress 14 migration guide says installing Cypress 14 requires Node.js 18 or newer, drops Linux distributions with glibc older than 2.28, and requires macOS 11 or newer because Cypress 14 upgrades Electron to 33.2.1. The guide also shows that plugin-file behavior must live in `setupNodeEvents()` and `devServer`, and that `supportFile` must be configured per testing type rather than at the top level. The current docs list the default support files as `cypress/support/e2e.{js,jsx,ts,tsx}` for E2E and `cypress/support/component.{js,jsx,ts,tsx}` for Component Testing.

When to choose

Use this when your CI and developer machines already meet the Node 18+, glibc 2.28+, and macOS 11+ baselines, and you can touch Cypress config in the same upgrade window. It is the right choice when the real blocker is stale config shape, not an unmovable OS or framework dependency.

Tradeoffs

You get onto the current major line covered by the official 14 migration docs and remove hidden reliance on legacy `cypress/plugins/index.js` and `cypress/support/index.js` assumptions. The cost is coordinated config churn across support files, node events, and any cross-origin tests affected by stricter `cy.origin()` requirements.

Cautions

The support-file and plugins-file changes are not new in Cypress 14 itself; they were introduced in the Cypress 10 config migration, so teams jumping from much older Cypress versions will absorb both Cypress 10 config changes and Cypress 14 runtime-baseline removals together. Multiple matching support files for a testing type now cause Cypress to error at load time.

Sources

Delay Cypress 14 until runtime and OS baselines are cleared

As of 2026-04-03, the official Cypress 14 migration guide still makes Node.js 18+ the minimum supported version for installing Cypress 14, and its prebuilt Linux binaries require glibc 2.28 or newer. The same guide says Cypress 14 requires macOS 11 or newer because of the Electron 33.2.1 upgrade. If your estate still includes Node 16, Amazon Linux 2, CentOS 7, RHEL 7, Ubuntu 14-18, or older macOS hosts, the upgrade is blocked at the platform layer before test-code cleanup matters.

When to choose

Use this when CI runners, developer laptops, or locked enterprise images cannot move off the removed runtime baselines yet. It is the safer choice when platform replacement would be the real project, and Cypress config rewrites are secondary.

Tradeoffs

You avoid a broken upgrade and keep migration scope bounded to platform modernization first. The downside is continued operational drag from older Cypress assumptions and a larger eventual migration if legacy config and runtime changes pile up.

Cautions

Do not treat this as only a JavaScript refactor. If the environment cannot install Cypress 14, support-file and plugin rewrites alone will not unblock the upgrade.

Sources

Use a staged migration: modernize config first, then move legacy component-testing stacks

The Cypress migration docs separate general config migration from Component Testing compatibility removals. As of 2026-04-03, Cypress 14 no longer ships support for React below 18, Angular below 17.2, Vue 2, Create React App component testing, Vue CLI component testing, and Svelte 3 or 4 component harnesses in the main binary. The guide documents temporary package-based workarounds for some older frameworks, such as `@cypress/react@8`, `@cypress/angular@2`, and `@cypress/svelte@2`, while also requiring support-file import changes in those fallback paths. This lets teams first normalize `supportFile`, `setupNodeEvents()`, and `devServer` usage, then retire legacy CT dependencies on a second pass.

When to choose

Use this when E2E coverage is the priority and Component Testing still depends on legacy framework versions or harness packages. It is the best fit for monorepos that can split config cleanup from frontend framework upgrades.

Tradeoffs

This reduces migration blast radius and lets modern E2E suites move sooner. The cost is temporary complexity because some deprecated CT harnesses must be installed separately and are explicitly documented as unsupported long term.

Cautions

The fallback CT harness packages are documented as temporary workarounds, not stable end states. Support-file imports may also need namespace changes such as moving from `cypress/react` to `@cypress/react` in those legacy fallback scenarios.

Sources

Facts updated: 2026-04-03
Published: 2026-04-03

Related questions

Try with your AI agent

$ npm install -g pocketlantern
$ pocketlantern init
# Restart Claude Code, Cursor, or your MCP client, then ask:
# "Cypress 14 Migration: supportFile Defaults and Older Runtime Support Removal — when and how should I migrate?"
Missing something? Request coverage