Principle:Cypress io Cypress Framework Detection
| Knowledge Sources | |
|---|---|
| Domains | Configuration, Component_Testing |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
An automatic dependency detection mechanism that identifies the UI framework and bundler used by a project by inspecting installed packages and their versions.
Description
Framework detection solves the configuration burden of specifying which framework and bundler a project uses. Instead of requiring manual configuration, Cypress inspects the project's node_modules and package.json to automatically detect frameworks (React, Vue, Angular, Svelte, Next.js) and bundlers (Vite, Webpack).
Detection follows a priority order: first checking for template frameworks (like Next.js, which bundle both a framework and bundler), then checking for library frameworks (like React) and separately detecting the bundler. This two-tier approach handles both opinionated frameworks and flexible library+bundler combinations.
Usage
Use this principle during the Cypress setup wizard when configuring component testing, or programmatically to auto-detect project configuration. It runs during the Launchpad onboarding flow and when scaffolding configuration files.
Theoretical Basis
Detection Algorithm:
1. For each template framework (Next.js, Nuxt, Angular CLI):
a. Check if ALL required dependencies are installed (via resolve-package-path)
b. Verify semver version constraints
c. If match → return { framework, bundler: framework.supportedBundlers[0] }
2. For each library framework (React, Vue, Svelte):
a. Check if library dependencies are satisfied
b. For each bundler (Vite, Webpack):
- Check if bundler is installed
- If library + bundler found → return { framework: library, bundler }
c. If library found but no bundler → return { framework: library }
3. If nothing detected → return { framework: undefined, bundler: undefined }