Workflow:Cypress io Cypress Project Setup and Configuration
| Knowledge Sources | |
|---|---|
| Domains | Testing, Configuration, Project_Setup |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
End-to-end process for initializing a new Cypress project, from first launch through framework detection, configuration scaffolding, browser selection, and verification of the testing environment.
Description
This workflow covers the first-time setup experience when a developer adds Cypress to a project. The Launchpad UI guides the user through selecting a testing type, detecting the project's frontend framework, scaffolding configuration files and example specs, choosing a browser, and verifying the setup works. The configuration system resolves settings from multiple sources with defined precedence: CLI flags, environment variables, config file, and defaults.
Key outputs:
- A complete cypress.config.{js,ts,mjs} file at the project root
- Scaffolded support files and example spec files
- Detected and validated browser list ready for test execution
Usage
Execute this workflow when adding Cypress to a project for the first time, or when reconfiguring Cypress after a major version upgrade. This is appropriate when the project does not yet have a cypress.config file, when switching between E2E and component testing types, or when the project's framework or bundler has changed.
Execution Steps
Step 1: Launch the Launchpad
Run the cypress open command to start the Cypress server and open the Launchpad UI in an Electron window. The Launchpad is a Vue 3 application that provides the guided setup experience. The server initializes the data-context layer which manages application state through a GraphQL schema.
Key considerations:
- The CLI validates the Node.js version and verifies the binary before launching
- The server binds to a local port and communicates with the UI via GraphQL over WebSocket
- First-time users see the welcome screen with testing type selection
- The data-context package manages all state through Nexus-based GraphQL resolvers
Step 2: Select Testing Type
Choose between E2E Testing and Component Testing. Each testing type has distinct configuration requirements and scaffolded file structures. The selection determines which configuration block is created and which example specs are generated.
Key considerations:
- E2E testing requires a running application server (or baseUrl configuration)
- Component testing requires framework and bundler detection
- Both types can coexist in the same project with separate configuration blocks
- The testing type selection can be changed later via the Launchpad
Step 3: Detect Framework and Bundler
For component testing, the scaffold-config package analyzes the project's dependencies to automatically detect the frontend framework (React, Vue, Angular, Svelte) and bundler (Vite, Webpack, Next.js, Nuxt). The detection examines package.json dependencies and config files to determine the correct adapter configuration.
Key considerations:
- Framework detection checks for specific dependency packages in node_modules
- Multiple framework/bundler combinations are supported with dedicated adapters
- Users can manually override the detected framework if auto-detection fails
- The detected configuration generates the appropriate devServer setup
Step 4: Scaffold Configuration Files
Generate the cypress.config file with appropriate defaults for the selected testing type. The config file is created using AST manipulation (via Babel) to produce syntactically correct JavaScript or TypeScript. Support files, fixture directories, and example spec files are also created.
Key considerations:
- The config file wraps settings in the defineConfig helper for type safety
- Configuration supports JS, TS, MJS, and CJS file formats
- The AST-based approach preserves existing config content when adding new testing types
- Example specs provide immediately-runnable tests demonstrating key Cypress features
Step 5: Detect and Select Browser
The launcher package scans the system for installed browsers compatible with Cypress. Browser detection is platform-specific: macOS uses application bundle identifiers, Linux checks binary paths and version output, Windows examines file system paths and registry. Users select their preferred browser from the detected list.
Key considerations:
- Supported browser families include Chromium (Chrome, Edge, Brave), Firefox, and Electron
- Each browser is validated for minimum version compatibility
- The Electron browser is always available as a bundled default
- Custom browser paths can be specified via the --browser CLI flag
Step 6: Validate Configuration
The configuration system validates all settings against their defined types and constraints. Validation covers value types, acceptable ranges, deprecated options, and breaking changes from previous versions. Invalid configurations produce clear error messages with remediation guidance.
Key considerations:
- Each config option has defined validation rules (type, range, allowed values)
- Breaking changes from prior Cypress versions are detected and reported
- Environment variables override config file values with proper type coercion
- The resolved configuration is frozen and made available throughout the application