cypress-devserver-esbuild

1.5.0 verified Fri May 01 auth: no javascript

Minimal esbuild dev server for Cypress component tests. Current stable version 1.5.0 adds Cypress 14 support while maintaining backward compatibility to Cypress 12 and 13. Tests are packaged as ESM bundles via a tiny express server. Written in TypeScript with full type definitions. Requires esbuild ^0.17.0 as a peer dependency. Unlike other Cypress dev servers (webpack, vite), this provides a lightweight, minimal config option for esbuild users.

Common errors

error Cannot find module 'cypress-devserver-esbuild' ↓

cause Missing package installation or incorrect import path.

fix

Run 'npm install -D cypress-devserver-esbuild' and use correct import.

error Module 'cypress-devserver-esbuild' has no exported member 'createEsbuildDevServer' ↓

cause Used default import instead of named import.

fix

Use 'import { createEsbuildDevServer } from 'cypress-devserver-esbuild'' or const { createEsbuildDevServer } = require('cypress-devserver-esbuild').

error Could not find a dev server implementation for this Cypress version ↓

cause Cypress version does not meet minimum requirement (12+).

fix

Upgrade Cypress to 12.x or higher.

error Error: esbuild is not installed. Add esbuild as a devDependency ↓

cause Missing peer dependency esbuild.

fix

Run 'npm install -D esbuild@^0.17.0'.

Warnings

gotcha Setting entryPoints in esbuild config is overwritten by dev server; tests are resolved via globby patterns, not esbuild's native globbing. ↓

fix Do not specify entryPoints in esbuild config; use specPattern in Cypress config to control test file matching.

gotcha If using CSS modules with separate CSS output files, must set hasCssFiles: true in options; otherwise CSS may not load. ↓

fix Add { hasCssFiles: true } to the second parameter of createEsbuildDevServer.

gotcha If test count produces too many chunks, browser's MaxConnectionsPerHost can slow tests. ↓

fix Set splitting: false in esbuild config, or use singleBundle: true in dev server options.

deprecated Deprecated import path: require('./src/dev-server') in documentation example may break with package updates. ↓

fix Use require('cypress-devserver-esbuild') or import { createEsbuildDevServer } from 'cypress-devserver-esbuild'.

gotcha Package requires Node.js 16+; older versions may fail on install or runtime. ↓

fix Upgrade Node.js to version 16 or higher.

Install

npm install cypress-devserver-esbuild

yarn add cypress-devserver-esbuild

pnpm add cypress-devserver-esbuild

Imports

createEsbuildDevServer

wrong

const createEsbuildDevServer = require('cypress-devserver-esbuild')

correct

import { createEsbuildDevServer } from 'cypress-devserver-esbuild'

Package ships ESM and CommonJS; named export only.

DevServerOptions

wrong

import { DevServerOptions } from 'cypress-devserver-esbuild'

correct

import type { DevServerOptions } from 'cypress-devserver-esbuild'

Type import only; not a runtime value.

EsbuildDevServerConfig
```
import type { EsbuildDevServerConfig } from 'cypress-devserver-esbuild'
```
Exported type for the esbuild configuration parameter.

Quickstart

Minimal Cypress config using esbuild dev server with custom output directory and single bundle mode.

const { defineConfig } = require('cypress');
const { createEsbuildDevServer } = require('cypress-devserver-esbuild');

module.exports = defineConfig({
  component: {
    devServer: createEsbuildDevServer({
      outdir: './dist-test',
      define: { 'process.env.API_KEY': JSON.stringify(process.env.API_KEY ?? '') }
    }, {
      singleBundle: true,
      port: 1234
    })
  }
});