or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

Cypress Vite Dev Server

Cypress Vite Dev Server provides Vite development server integration for Cypress Component Testing. It enables developers to run component tests with Vite's fast build system and hot module replacement, serving as a bridge between Cypress's component testing framework and Vite's development server.

Package Information

Package Name: @cypress/vite-dev-server
Package Type: npm
Language: TypeScript
Installation: npm install @cypress/vite-dev-server
Peer Dependencies: vite >= 2.1.3

Core Imports

import { startDevServer, StartDevServer, ResolvedDevServerConfig } from "@cypress/vite-dev-server";
import type { UserConfig } from "vite";
import { EventEmitter } from "events";

For CommonJS:

const { startDevServer } = require("@cypress/vite-dev-server");
const { EventEmitter } = require("events");

Basic Usage

// In cypress/plugins/index.js (CommonJS)
const { startDevServer } = require('@cypress/vite-dev-server');

module.exports = (on, config) => {
  on('dev-server:start', async (options) => {
    return startDevServer({ options });
  });

  return config;
};

// Or in cypress/plugins/index.ts (ES Modules)
import { startDevServer } from '@cypress/vite-dev-server';

export default (on, config) => {
  on('dev-server:start', async (options) => {
    return startDevServer({ options });
  });

  return config;
};

Architecture

The Cypress Vite Dev Server is built around several key components:

Main Entry Point: startDevServer function that orchestrates the server setup
Server Configuration: Automatic resolution of Vite configuration with Cypress-specific settings
Plugin System: Custom Vite plugin that handles Cypress integration requirements
Hot Module Replacement: Automatic test re-running when source files change
Client-side Integration: Initialization script that connects Cypress test runner with Vite-served content

The system works by taking user Vite configuration and Cypress options, creating a custom Vite plugin for Cypress integration, configuring the dev server with proper base path (__cypress/src/), and providing HTML template and initialization script for the test environment.

Key Architecture Components:

Request Routing: All requests to __cypress/iframes/... are routed to the dev server as __cypress/src/index.html
Client Initialization: The initCypressTests.js client script handles loading support files and specs
Hot Reloading: File changes trigger test re-runs via dev-server:compile:success events
Error Handling: Vite's error overlay is integrated for build/compilation errors

Capabilities

Dev Server Startup

Starts a Vite development server configured for Cypress component testing with automatic port allocation and Cypress-specific plugins.

/**
 * Starts a Vite development server configured for Cypress component testing
 * @param startDevServerArgs - Configuration object containing Cypress options and optional Vite config
 * @returns Promise resolving to server configuration with port and HTTP server instance
 */
function startDevServer(startDevServerArgs: StartDevServer): Promise<ResolvedDevServerConfig>;

interface StartDevServer {
  /** Cypress options object containing specs, config, and devServerEvents */
  options: Options;
  /** Optional user Vite configuration to merge with Cypress requirements */
  viteConfig?: UserConfig;
}

interface Options {
  /** Array of Cypress spec files to be tested */
  specs: CypressSpec[];
  /** Cypress configuration object with projectRoot, supportFile, etc. */
  config: {
    projectRoot: string;
    supportFile?: string;
    [key: string]: string | undefined;
  };
  /** Event emitter for dev server compilation events */
  devServerEvents: EventEmitter;
  /** Additional options as key-value pairs */
  [key: string]: unknown;
}

interface ResolvedDevServerConfig {
  /** Port number where the dev server is running */
  port: number;
  /** HTTP server instance for the dev server */
  server: Server;
}

Usage Example:

import { startDevServer } from "@cypress/vite-dev-server";
import type { UserConfig } from "vite";
import { EventEmitter } from "events";

// Create event emitter for dev server events
const devServerEvents = new EventEmitter();

// Basic usage with Cypress options only
const server1 = await startDevServer({
  options: {
    specs: [
      {
        name: 'Button.spec.tsx',
        relative: 'src/components/Button.spec.tsx',
        absolute: '/project/src/components/Button.spec.tsx'
      }
    ],
    config: { 
      projectRoot: '/path/to/project',
      supportFile: 'cypress/support/component.ts'
    },
    devServerEvents
  }
});

// Advanced usage with custom Vite configuration
const customViteConfig: UserConfig = {
  plugins: [],
  resolve: {
    alias: { '@': '/src' }
  },
  define: {
    'process.env.NODE_ENV': JSON.stringify('test')
  }
};

const server2 = await startDevServer({
  options: {
    specs: [
      {
        name: 'App.spec.tsx',
        relative: 'src/App.spec.tsx', 
        absolute: '/project/src/App.spec.tsx'
      }
    ],
    config: { 
      projectRoot: '/path/to/project',
      supportFile: 'cypress/support/component.ts'
    },
    devServerEvents
  },
  viteConfig: customViteConfig
});

console.log(`Server running on port ${server2.port}`);

// Listen for compilation events
devServerEvents.on('dev-server:compile:success', () => {
  console.log('Tests recompiled successfully');
});

Types

// Re-exported from Vite for convenience
type UserConfig = import('vite').UserConfig;
type Server = import('http').Server;
type EventEmitter = import('events').EventEmitter;

// Cypress-specific types (external dependency)
interface CypressSpec {
  name: string;
  relative: string;
  absolute: string;
  // Additional Cypress spec properties as needed
}