or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

framework-support.md index.md main-devserver.md module-sourcing.md

tile.json

Main Dev Server API

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

Capabilities

devServer Function

Main entry point that creates and configures a webpack dev server instance for Cypress component testing.

/**
 * Creates & returns a WebpackDevServer for serving files related to Cypress Component Testing
 * @param devServerConfig - Configuration object containing specs, Cypress config, and webpack options
 * @returns Promise resolving to Cypress.ResolvedDevServerConfig with port and close method
 */
function devServer(devServerConfig: WebpackDevServerConfig): Promise<Cypress.ResolvedDevServerConfig>;

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

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

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

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

Usage Examples:

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

// Basic usage with framework detection
export default defineConfig({
  component: {
    devServer(devServerConfig) {
      return devServer({
        ...devServerConfig,
        framework: 'react'
      });
    }
  }
});

// Advanced usage with custom webpack config
export default defineConfig({
  component: {
    devServer(devServerConfig) {
      return devServer({
        ...devServerConfig,
        framework: 'vue',
        webpackConfig: {
          resolve: {
            alias: {
              '@': path.resolve(__dirname, 'src')
            }
          },
          module: {
            rules: [
              {
                test: /\.vue$/,
                loader: 'vue-loader'
              }
            ]
          }
        }
      });
    }
  }
});

// Using function-based webpack config
export default defineConfig({
  component: {
    devServer(devServerConfig) {
      return devServer({
        ...devServerConfig,
        framework: 'react',
        webpackConfig: async () => {
          const baseConfig = await import('./webpack.config.js');
          return {
            ...baseConfig.default,
            mode: 'development'
          };
        }
      });
    }
  }
});

devServer.create Static Method

Internal method for synchronously creating the webpack server instance without starting it. Primarily used for testing.

/**
 * Synchronously create the webpack server instance, without starting.
 * Useful for testing
 * @internal
 * @param devServerConfig - Same configuration as main devServer function
 * @returns Promise resolving to server instance with version info
 */
devServer.create(devServerConfig: WebpackDevServerConfig): Promise<DevServerCreateResult>;

interface DevServerCreateResult {
  /** Webpack dev server version (currently always 5) */
  version: 5;
  /** Webpack dev server instance */
  server: WebpackDevServer5;
  /** Webpack compiler instance */
  compiler: Compiler;
}

Configuration Details

WebpackDevServerConfig Properties

specs

Array of Cypress spec files to be served by the webpack dev server.

specs: Cypress.Spec[]

cypressConfig

Cypress configuration options containing project settings and paths.

cypressConfig: Cypress.PluginConfigOptions

Key properties used:

projectRoot: Root directory of the project
supportFile: Path to support file
devServerPublicPathRoute: Public path for dev server assets
indexHtmlFile: Custom HTML template file

devServerEvents

Event emitter for dev server lifecycle events and communication.

devServerEvents: NodeJS.EventEmitter

onConfigNotFound (Optional)

Callback function invoked when webpack configuration cannot be automatically detected.

onConfigNotFound?: (devServer: 'webpack', cwd: string, lookedIn: string[]) => void

Parameters:

devServer: Always 'webpack' for this package
cwd: Current working directory where search was performed
lookedIn: Array of paths that were searched for webpack config

webpackConfig (Optional)

User's webpack configuration that will be merged with Cypress-specific settings.

webpackConfig?: ConfigHandler

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

Can be:

Object: Direct webpack configuration object
Function: Function returning webpack config (can be async)

framework (Optional)

Target framework for component testing. Determines which preset handlers to use.

framework?: Frameworks

type Frameworks = 'react' | 'vue' | 'svelte' | 'next' | 'angular' | string;

Supported values:

'react': React framework with JSX support
'vue': Vue.js framework with SFC support
'svelte': Svelte framework support
'next': Next.js framework with specialized webpack handling
'angular': Angular framework with CLI integration
Custom string: Third-party framework definitions following cypress-ct-* pattern

options (Optional)

Framework-specific configuration options.

options?: {
  projectConfig: Cypress.AngularDevServerProjectConfig;
}

Currently only used for Angular framework configuration.

Return Value

The devServer function returns a Promise that resolves to Cypress.ResolvedDevServerConfig:

interface Cypress.ResolvedDevServerConfig {
  /** Port number where the dev server is running */
  port: number;
  /** Function to close the dev server (mainly for testing) */
  close: (done?: () => void) => Promise<void>;
}

Error Handling

The devServer function may reject with errors in the following cases:

Invalid port: When the dev server port is not a valid number
Webpack compilation errors: When there are errors in the webpack configuration or user code
Framework handler errors: When framework-specific handlers encounter issues
Module sourcing errors: When required webpack dependencies cannot be found or loaded

Debugging

Enable debug mode with webpack-bundle-analyzer for troubleshooting:

DEBUG=cypress-verbose:webpack-dev-server:bundle-analyzer cypress open

This will generate a webpack-bundle-analyzer report to help identify bundle size issues and chunk load errors.