Module Sourcing and Configuration

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

Capabilities

Module Sourcing System

The module sourcing system loads webpack and related dependencies from the user's project rather than bundling them, ensuring version compatibility and allowing users to control their build toolchain.

interface SourceRelativeWebpackResult {
  /** Framework-specific dependency (if applicable) */
  framework: SourcedDependency | null;
  /** Sourced webpack module with version info */
  webpack: SourcedWebpack;
  /** Sourced webpack-dev-server module */
  webpackDevServer: SourcedWebpackDevServer;
  /** Sourced HTML webpack plugin */
  htmlWebpackPlugin: SourcedHtmlWebpackPlugin;
}

Base Dependency Interface

All sourced dependencies extend this base interface:

interface SourcedDependency {
  /** Import path used to load the dependency */
  importPath: string;
  /** Package.json metadata for version and name info */
  packageJson: PackageJson;
}

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

Webpack Module Sourcing

Sources the webpack compiler from the user's project:

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

Usage:

• Ensures compatibility with user's webpack version
• Supports both webpack 4 and 5
• Provides access to webpack constructor for creating compiler instances

Webpack Dev Server Sourcing

Sources the webpack-dev-server from the user's project:

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

Features:

• Version detection for API compatibility
• Constructor access for server instantiation
• Support for both v4 and v5 APIs

HTML Webpack Plugin Sourcing

Sources the HTML webpack plugin for template processing:

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

Purpose:

• Template generation for component testing
• Asset injection into HTML
• Version-specific configuration handling

Module Resolution System

Node.js Module Extensions

Enhanced Node.js Module interface for internal module resolution:

type ModuleClass = typeof Module & {
  /** Internal Node.js module loader */
  _load(id: string, parent: Module, isMain: boolean): any;
  /** Internal filename resolution */
  _resolveFilename(request: string, parent: Module, isMain: boolean, options?: { paths: string[] }): string;
  /** Module cache for loaded modules */
  _cache: Record<string, Module>;
};

Usage:

• Custom module resolution for sourcing dependencies
• Cache management for performance
• Path resolution from user's project context

Dependency Resolution Process

The module sourcing system follows this resolution process:

1. Project Context Detection: Determine user's project root and node_modules structure
2. Dependency Location: Search for required modules in user's dependencies
3. Version Detection: Read package.json to determine major versions
4. Module Loading: Load modules using Node.js require system
5. Fallback Handling: Use bundled versions if user dependencies not found
6. Cache Management: Cache loaded modules for performance

Configuration File Detection

Supported Configuration Files

The system automatically detects webpack configuration files:

const configFiles: string[] = [
  'webpack.config.ts',
  'webpack.config.js',
  'webpack.config.mjs',
  'webpack.config.cjs'
];

Detection Order:

1. TypeScript config (webpack.config.ts)
2. Standard JavaScript (webpack.config.js)
3. ES Module JavaScript (webpack.config.mjs)
4. CommonJS JavaScript (webpack.config.cjs)

Configuration Loading

Usage Examples:

// webpack.config.js - Standard configuration
module.exports = {
  entry: './src/index.js',
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        use: 'babel-loader'
      }
    ]
  }
};

// webpack.config.ts - TypeScript configuration
import { Configuration } from 'webpack';

const config: Configuration = {
  entry: './src/index.ts',
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        use: 'ts-loader'
      }
    ]
  }
};

export default config;

// webpack.config.mjs - ES Module configuration
export default {
  entry: './src/index.js',
  mode: 'development'
};

Bundle Analysis and Debugging

Bundle Analyzer Integration

Built-in webpack-bundle-analyzer support for debugging bundle issues:

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

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

Usage:

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

# This will generate a webpack-bundle-analyzer report

Features:

• Bundle size visualization
• Chunk analysis for load performance
• Dependency tree exploration
• Source map size analysis

Debug Output

When bundle analyzer is enabled, the system provides:

• Bundle Composition: Visual breakdown of bundle contents
• Size Analysis: Parsed vs gzipped sizes for all chunks
• Dependency Mapping: Which modules contribute to bundle size
• Performance Insights: Identification of large dependencies
• Source Map Analysis: Source map size vs code size ratios

Error Handling and Fallbacks

Module Resolution Errors

When user dependencies cannot be found:

// onConfigNotFound callback will be triggered
onConfigNotFound?: (devServer: 'webpack', cwd: string, lookedIn: string[]) => void

Error Scenarios:

• Missing webpack dependency in user project
• Incompatible webpack version
• Corrupted node_modules
• Missing peer dependencies

Fallback Strategy

1. Primary Resolution: Use user's project dependencies
2. Bundled Fallback: Use versions bundled with @cypress/webpack-dev-server
3. Error Reporting: Inform user of missing dependencies
4. Graceful Degradation: Provide basic functionality where possible

Version Compatibility

Supported Versions:

• Webpack: 4.x and 5.x
• Webpack Dev Server: 4.x and 5.x
• HTML Webpack Plugin: 4.x and 5.x

Compatibility Matrix:

| Webpack | Dev Server | HTML Plugin | Support |
|---------|------------|-------------|---------|
| 4.x     | 4.x        | 4.x         | ✅      |
| 5.x     | 5.x        | 5.x         | ✅      |
| 4.x     | 5.x        | 4.x         | ❌      |
| 5.x     | 4.x        | 5.x         | ❌      |

Advanced Configuration

Custom Module Sourcing

For advanced scenarios, you can influence module sourcing:

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

export default defineConfig({
  component: {
    devServer(devServerConfig) {
      return devServer({
        ...devServerConfig,
        webpackConfig: async () => {
          // Custom webpack loading logic
          const webpack = require('webpack');
          const path = require('path');
          
          return {
            resolve: {
              modules: [
                path.resolve(__dirname, 'custom_modules'),
                'node_modules'
              ]
            }
          };
        }
      });
    }
  }
});

Performance Optimization

Best Practices:

• Keep webpack and related dependencies up to date
• Use webpack 5 for better performance and smaller bundles
• Enable caching in webpack configuration
• Monitor bundle analyzer output for optimization opportunities
• Use appropriate source map settings for debugging vs performance balance