or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

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

framework-support.mddocs/

Framework Support

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

Capabilities

Supported Frameworks

@cypress/webpack-dev-server provides built-in support for major frontend frameworks with intelligent configuration detection and optimization.

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

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

Framework Detection

Utility function to identify third-party framework definitions.

/**
 * Checks if a framework string matches third-party definition patterns
 * @param framework - Framework identifier string
 * @returns true if framework is a third-party definition
 */
function isThirdPartyDefinition(framework: string): boolean;

Third-party frameworks must follow naming conventions:

  • Global prefix pattern: cypress-ct-* (e.g., cypress-ct-solid)
  • Namespaced pattern: @org/cypress-ct-* (e.g., @myorg/cypress-ct-lit)

Usage Examples:

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

console.log(isThirdPartyDefinition('react')); // false
console.log(isThirdPartyDefinition('cypress-ct-solid')); // true
console.log(isThirdPartyDefinition('@myorg/cypress-ct-lit')); // true

Framework-Specific Handlers

React Framework

Standard React support with JSX transformation and hot module replacement.

Configuration:

// Automatic detection and configuration
{
  framework: 'react'
}

// With custom webpack config
{
  framework: 'react',
  webpackConfig: {
    resolve: {
      alias: {
        '@': path.resolve(__dirname, 'src')
      }
    }
  }
}

Features:

  • JSX/TSX transformation via Babel or TypeScript
  • React Fast Refresh for hot reloading
  • Automatic React import handling
  • Source map support for debugging

Vue.js Framework

Vue Single File Component (SFC) support with full feature set.

Configuration:

{
  framework: 'vue'
}

Features:

  • Vue SFC compilation (.vue files)
  • Vue 3 Composition API support
  • Scoped CSS processing
  • Vue devtools integration
  • TypeScript support in SFCs

Svelte Framework

Svelte component compilation with preprocessing support.

Configuration:

{
  framework: 'svelte'
}

Features:

  • Svelte component compilation
  • Preprocessing support (TypeScript, SCSS, etc.)
  • Svelte stores integration
  • Hot module replacement

Next.js Framework

Advanced Next.js integration with specialized webpack configuration handling.

interface NextHandlerResult extends PresetHandlerResult {
  frameworkConfig: Configuration;
  sourceWebpackModulesResult: SourceRelativeWebpackResult;
}

Configuration:

{
  framework: 'next'
}

Features:

  • Next.js webpack config loading and merging
  • Built-in CSS/SCSS support
  • Image optimization compatibility
  • API route handling (for component testing)
  • TypeScript configuration inheritance
  • SWC compiler integration

Usage Example:

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

export default defineConfig({
  component: {
    devServer(devServerConfig) {
      return devServer({
        ...devServerConfig,
        framework: 'next'
        // Next.js config will be automatically detected from next.config.js
      });
    }
  }
});

Angular Framework

Comprehensive Angular integration with CLI-based configuration support.

interface AngularWebpackDevServerConfig extends WebpackDevServerConfig {
  framework: 'angular';
  options?: {
    projectConfig: Cypress.AngularDevServerProjectConfig;
  };
}

interface AngularJsonProjectConfig {
  projectType: string;
  root: string;
  sourceRoot: string;
  architect: {
    build: { 
      options: BuildOptions;
      configurations?: {
        [configuration: string]: BuildOptions;
      };
    };
  };
}

type BuildOptions = Record<string, any>;

Configuration:

{
  framework: 'angular',
  options: {
    projectConfig: {
      // Angular project configuration from angular.json
      root: 'projects/my-app',
      sourceRoot: 'projects/my-app/src',
      // ... other Angular CLI options
    }
  }
}

Features:

  • Angular CLI webpack config integration
  • TypeScript compilation with Angular decorators
  • Angular template and style processing
  • Dependency injection support
  • Zone.js integration for component testing
  • Custom Angular build configurations

Usage Example:

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

export default defineConfig({
  component: {
    devServer(devServerConfig) {
      return devServer({
        ...devServerConfig,
        framework: 'angular',
        options: {
          projectConfig: {
            root: '.',
            sourceRoot: 'src',
            architect: {
              build: {
                options: {
                  main: 'src/main.ts',
                  tsConfig: 'tsconfig.app.json'
                }
              }
            }
          }
        }
      });
    }
  }
});

Third-Party Framework Support

Custom Framework Integration

Support for community-maintained framework integrations through a plugin system.

Naming Convention:

  • Global: cypress-ct-{framework} (e.g., cypress-ct-solid, cypress-ct-lit)
  • Namespaced: @{org}/cypress-ct-{framework} (e.g., @solidjs/cypress-ct-solid)

Usage:

{
  framework: 'cypress-ct-solid' // Will be detected as third-party
}

Third-Party Framework Examples:

  • cypress-ct-solid: Solid.js support
  • cypress-ct-lit: Lit element support
  • cypress-ct-stencil: Stencil components
  • @storybook/cypress-ct-storybook: Storybook integration

Framework Handler Architecture

PresetHandlerResult Interface

All framework handlers return a standardized result structure:

interface PresetHandlerResult {
  /** Framework-specific webpack configuration to be merged */
  frameworkConfig: Configuration;
  /** Sourced webpack modules from user's project */
  sourceWebpackModulesResult: SourceRelativeWebpackResult;
}

Handler Execution Flow

  1. Framework Detection: Identify the target framework from configuration
  2. Module Sourcing: Load webpack dependencies from user's project
  3. Config Generation: Generate framework-specific webpack configuration
  4. Config Merging: Merge framework config with user config and Cypress defaults
  5. Server Creation: Create webpack dev server with final configuration

Custom Handler Implementation

For advanced use cases, you can bypass framework handlers:

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

export default defineConfig({
  component: {
    devServer(devServerConfig) {
      return devServer({
        ...devServerConfig,
        // No framework specified - uses default webpack config
        webpackConfig: {
          // Full custom webpack configuration
          module: {
            rules: [
              // Custom loaders and rules
            ]
          },
          plugins: [
            // Custom plugins
          ]
        }
      });
    }
  }
});

Configuration Priority

Framework configurations are merged in the following priority order (highest to lowest):

  1. Cypress Internal Overrides: Required settings for component testing
  2. User webpackConfig: Explicitly provided webpack configuration
  3. Framework Handler Config: Framework-specific optimizations
  4. Default Configuration: Base webpack settings for component testing

This ensures that Cypress-specific requirements are never overridden while allowing maximum flexibility for user customization.