or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

framework-support.mdindex.mdmain-devserver.mdmodule-sourcing.md
tile.json

index.mddocs/

@cypress/webpack-dev-server

@cypress/webpack-dev-server implements the APIs for the object-syntax of Cypress Component-testing webpack dev server. It provides seamless integration between Cypress component testing and webpack dev server, supporting multiple frontend frameworks including React, Vue, Angular, Next.js, and Svelte.

Package Information

  • Package Name: @cypress/webpack-dev-server
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @cypress/webpack-dev-server (usually installed automatically with Cypress)
  • Peer Dependencies: cypress >=15.0.0

Core Imports

import { devServer } from "@cypress/webpack-dev-server";

For CommonJS:

const { devServer } = require("@cypress/webpack-dev-server");

Basic Usage

Object API (Simple Configuration)

import { defineConfig } from 'cypress';

export default defineConfig({
  component: {
    devServer: {
      framework: 'react',
      bundler: 'webpack',
      // webpackConfig will be automatically inferred
    }
  }
});

Function API (Advanced Configuration)

import { devServer } from '@cypress/webpack-dev-server';
import { defineConfig } from 'cypress';

export default defineConfig({
  component: {
    devServer(devServerConfig) {
      return devServer({
        ...devServerConfig,
        framework: 'react',
        webpackConfig: require('./webpack.config.js')
      });
    }
  }
});

Architecture

@cypress/webpack-dev-server is built around several key components:

  • devServer Function: Main entry point that creates and configures a webpack dev server instance. Uses async/await pattern with Promise-based API and creates WebpackDevServer 5 instances exclusively.
  • Framework Handlers: Specialized configuration handlers for different frameworks (React, Vue, Angular, Next.js, Svelte). Next.js handler loads Next.js config and webpack settings. Angular handler integrates with Angular CLI build system.
  • Module Sourcing: Advanced system for loading webpack dependencies from the user's project using Node.js module resolution. Falls back to bundled versions when user dependencies unavailable. Overrides Module._load and Module._resolveFilename for consistent webpack resolution.
  • Configuration Merging: Intelligent merging of user webpack config with Cypress-specific optimizations including custom Cypress webpack plugin, HTML template handling, and development-specific settings.
  • Debug Integration: Built-in webpack-bundle-analyzer support for troubleshooting with cypress-verbose:webpack-dev-server:bundle-analyzer debug namespace.

Capabilities

Main Dev Server

Core functionality for creating and managing webpack dev server instances for Cypress component testing.

function devServer(devServerConfig: WebpackDevServerConfig): Promise<Cypress.ResolvedDevServerConfig>;

type WebpackDevServerConfig = {
  specs: Cypress.Spec[];
  cypressConfig: Cypress.PluginConfigOptions;
  devServerEvents: NodeJS.EventEmitter;
  onConfigNotFound?: (devServer: 'webpack', cwd: string, lookedIn: string[]) => void;
  webpackConfig?: ConfigHandler;
} & FrameworkConfig;

type FrameworkConfig = {
  framework?: Exclude<Frameworks, 'angular'>;
} | {
  framework: 'angular';
  options?: {
    projectConfig: Cypress.AngularDevServerProjectConfig;
  };
}

type ConfigHandler = Partial<Configuration> | (() => Partial<Configuration> | Promise<Partial<Configuration>>);

type Frameworks = Extract<Cypress.DevServerConfigOptions, { bundler: 'webpack' }>['framework'];

Main Dev Server API

Framework Support

Framework-specific configuration and optimization for popular frontend frameworks and build tools.

type Frameworks = Extract<Cypress.DevServerConfigOptions, { bundler: 'webpack' }>['framework'];

function isThirdPartyDefinition(framework: string): boolean;

type FrameworkConfig = {
  framework?: Exclude<Frameworks, 'angular'>;
} | {
  framework: 'angular';
  options?: {
    projectConfig: Cypress.AngularDevServerProjectConfig;
  };
}

Framework Support

Module Sourcing and Configuration

System for sourcing webpack-related dependencies from the user's project and creating optimized configurations.

interface SourceRelativeWebpackResult {
  framework: SourcedDependency | null;
  webpack: SourcedWebpack;
  webpackDevServer: SourcedWebpackDevServer;
  htmlWebpackPlugin: SourcedHtmlWebpackPlugin;
}

interface SourcedWebpack extends SourcedDependency {
  module: Function;
  majorVersion: 4 | 5;
}

interface SourcedWebpackDevServer extends SourcedDependency {
  module: { new (...args: unknown[]): unknown };
  majorVersion: 4 | 5;
}

Module Sourcing

Types

Core Configuration Types

type WebpackDevServerConfig = {
  /** Array of test spec files to be served */
  specs: Cypress.Spec[];
  /** Cypress configuration options */
  cypressConfig: Cypress.PluginConfigOptions;
  /** Event emitter for dev server events */
  devServerEvents: NodeJS.EventEmitter;
  /** Optional callback when webpack config not found */
  onConfigNotFound?: (devServer: 'webpack', cwd: string, lookedIn: string[]) => void;
  /** User's webpack configuration (object or function) */
  webpackConfig?: ConfigHandler;
} & FrameworkConfig;

type FrameworkConfig = {
  /** Framework configuration for non-Angular frameworks */
  framework?: Exclude<Frameworks, 'angular'>;
} | {
  /** Angular framework configuration with options */
  framework: 'angular';
  options?: {
    projectConfig: Cypress.AngularDevServerProjectConfig;
  };
}

type ConfigHandler = 
  | Partial<Configuration>
  | (() => Partial<Configuration> | Promise<Partial<Configuration>>);

type Frameworks = Extract<Cypress.DevServerConfigOptions, { bundler: 'webpack' }>['framework'];

Module Sourcing Types

interface SourcedDependency {
  /** Import path for the dependency */
  importPath: string;
  /** Package.json metadata */
  packageJson: PackageJson;
}

interface PackageJson {
  name: string;
  version: string;
}

interface SourcedWebpack extends SourcedDependency {
  /** Webpack constructor function */
  module: Function;
  /** Major version (4 or 5) */
  majorVersion: 4 | 5;
}

interface SourcedWebpackDevServer extends SourcedDependency {
  /** WebpackDevServer constructor */
  module: { new (...args: unknown[]): unknown };
  /** Major version (4 or 5) */
  majorVersion: 4 | 5;
}

interface SourcedHtmlWebpackPlugin extends SourcedDependency {
  /** HTML webpack plugin module */
  module: unknown;
  /** Major version (4 or 5) */
  majorVersion: 4 | 5;
}

Internal Types

interface PresetHandlerResult {
  /** Framework-specific webpack configuration */
  frameworkConfig: Configuration;
  /** Result of sourcing webpack modules from user project */
  sourceWebpackModulesResult: SourceRelativeWebpackResult;
}

type ModuleClass = typeof Module & {
  _load(id: string, parent: Module, isMain: boolean): any;
  _resolveFilename(request: string, parent: Module, isMain: boolean, options?: { paths: string[] }): string;
  _cache: Record<string, Module>;
};

Constants

/** Supported webpack configuration file names */
const configFiles: string[] = [
  'webpack.config.ts',
  'webpack.config.js', 
  'webpack.config.mjs',
  'webpack.config.cjs'
];

/** Debug namespace for webpack bundle analyzer */
const WBADebugNamespace: string = 'cypress-verbose:webpack-dev-server:bundle-analyzer';

Utility Functions

/** Checks if webpack bundle analyzer debug mode is enabled */
function isWebpackBundleAnalyzerEnabled(): boolean;

/** Checks if a framework is a third-party definition */
function isThirdPartyDefinition(framework: string): boolean;