tessl/npm-cypress--webpack-dev-server

Implements the APIs for the object-syntax of the Cypress Component-testing webpack dev server

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

@cypress/webpack-dev-server

Name: tessl/npm-cypress--webpack-dev-server
Author: tessl

@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;