ScreenshotNeo

BlogHow-to

How to Fix Cypress Cannot Find the @badeball/cypress-cucumber-preprocessor/steps Module

Fix Cypress’s missing Badeball Cucumber steps module with the right package, TypeScript resolution, plugin, bundler, globs, and a complete working setup.

By the ScreenshotNeo team30 September 20268 min read

How to Fix Cypress Cannot Find the @badeball/cypress-cucumber-preprocessor/steps Module

If Cypress reports Cannot find module '@badeball/cypress-cucumber-preprocessor/steps', the usual cause is a missing or incorrectly resolved package entry point. Install the maintained scoped package, configure its Cypress plugin and bundler, make TypeScript understand conditional exports, and ensure your step-definition files match the configured search paths.

This guide gives you a complete working setup, then narrows down the common variations: JavaScript versus TypeScript, esbuild versus Browserify or Webpack, old package migrations, custom step globs, monorepos, and stale dependency caches.

What the error means

The import below is a subpath export supplied by the maintained Badeball package:

import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor/steps';

Node, Cypress, or the TypeScript language service cannot resolve that subpath when one of these conditions is true:

  • @badeball/cypress-cucumber-preprocessor is not installed in the project running Cypress.
  • The obsolete unscoped package is installed or imported instead.
  • TypeScript is using a module-resolution mode that does not understand the package’s conditional exports.
  • The Cypress plugin was not registered, the bundler was not configured, or the config was not returned.
  • Your feature files or step files are outside the configured patterns.
  • node_modules is incomplete or your editor has cached an older package layout.

Fastest supported fix

  1. From the directory containing the Cypress package.json, install the maintained package:
npm install --save-dev @badeball/cypress-cucumber-preprocessor

Do not install both this scoped package and the old cypress-cucumber-preprocessor package. The old package is severely outdated according to the maintainer FAQ, and mixing names can leave imports, plugins, and lockfiles pointing at different implementations.

The feature pattern, plugin, bundler, and step-definition search paths must all connect.
The feature pattern, plugin, bundler, and step-definition search paths must all connect.

For TypeScript, add conditional-export support:

{
  "compilerOptions": {
    "moduleResolution": "node16"
  }
}

Then configure Cypress with the plugin, an esbuild preprocessor, and a .feature spec pattern. A complete configuration appears below.

Complete TypeScript setup with esbuild

The maintainers recommend esbuild when you do not have a special bundler requirement. Install the integration and TypeScript support:

npm install --save-dev \
  @badeball/cypress-cucumber-preprocessor \
  @bahmutov/cypress-esbuild-preprocessor \
  esbuild \
  typescript

Create or update cypress.config.ts:

import { defineConfig } from 'cypress';
import createBundler from '@bahmutov/cypress-esbuild-preprocessor';
import { addCucumberPreprocessorPlugin } from '@badeball/cypress-cucumber-preprocessor';
import { createEsbuildPlugin } from '@badeball/cypress-cucumber-preprocessor/esbuild';

export default defineConfig({
  e2e: {
    specPattern: '**/*.feature',
    async setupNodeEvents(on, config) {
      await addCucumberPreprocessorPlugin(on, config);

      on('file:preprocessor', createBundler({
        plugins: [createEsbuildPlugin(config)],
      }));

      return config;
    },
  },
});

Three details matter here:

  • addCucumberPreprocessorPlugin(on, config) connects the feature processing lifecycle.
  • createEsbuildPlugin(config) lets esbuild compile feature imports and step-definition references correctly.
  • return config preserves the changes made by the plugin. Omitting it can make the setup appear to run while silently dropping configuration.

Use a matching tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["ES2020", "DOM"],
    "module": "Node16",
    "moduleResolution": "node16",
    "esModuleInterop": true,
    "strict": true,
    "types": ["cypress", "node"]
  },
  "include": ["cypress/**/*.ts", "cypress/**/*.feature"]
}

The important setting is moduleResolution: node16. The package uses conditional exports, so older resolution modes may find the package root but fail to find /steps.

Minimal project layout

A layout that works with the default search paths looks like this:

your-project/
├── package.json
├── tsconfig.json
├── cypress.config.ts
└── cypress/
    ├── e2e/
    │   ├── login.feature
    │   └── login.ts
    └── support/
        └── step_definitions/
            └── common.ts

Example feature file:

Feature: Login

  Scenario: Valid credentials
    Given I visit the login page
    When I submit valid credentials
    Then I should see the dashboard

Example step file using the failing import:

import { Given, When, Then } from '@badeball/cypress-cucumber-preprocessor/steps';

Given('I visit the login page', () => {
  cy.visit('/login');
});

When('I submit valid credentials', () => {
  cy.get('[name=email]').type('user@example.test');
  cy.get('[name=password]').type('correct-password');
  cy.get('button[type=submit]').click();
});

Then('I should see the dashboard', () => {
  cy.url().should('include', '/dashboard');
});

The default step-definition search paths cover matching files under cypress/e2e and cypress/support/step_definitions. Step definitions are resolved through configurable stepDefinitions search paths, so a valid import can still produce missing-step behavior when the file itself is outside those globs.

When node16 module resolution is not possible

Some repositories cannot change their module settings because another tool requires the older TypeScript behavior. In that case, add a path mapping that points subpath imports at the package’s generated entry points:

TypeScript can resolve the /steps entry point when its module-resolution mode understands conditional exports.
TypeScript can resolve the /steps entry point when its module-resolution mode understands conditional exports.
{
  "compilerOptions": {
    "moduleResolution": "node",
    "baseUrl": ".",
    "paths": {
      "@badeball/cypress-cucumber-preprocessor/*": [
        "./node_modules/@badeball/cypress-cucumber-preprocessor/dist/subpath-entrypoints/*"
      ]
    }
  }
}

This is a compatibility fallback. It adds maintenance overhead because the mapping is tied to the package’s internal distribution layout. Prefer node16 when your TypeScript and build pipeline can support it; use the mapping when changing resolution would break other dependencies.

JavaScript projects

JavaScript projects do not need TypeScript’s declaration lookup, but they still need the package, plugin, bundler, and feature pattern. Use cypress.config.js:

const { defineConfig } = require('cypress');
const createBundler = require('@bahmutov/cypress-esbuild-preprocessor');
const { addCucumberPreprocessorPlugin } = require('@badeball/cypress-cucumber-preprocessor');
const { createEsbuildPlugin } = require('@badeball/cypress-cucumber-preprocessor/esbuild');

module.exports = defineConfig({
  e2e: {
    specPattern: '**/*.feature',
    async setupNodeEvents(on, config) {
      await addCucumberPreprocessorPlugin(on, config);
      on('file:preprocessor', createBundler({
        plugins: [createEsbuildPlugin(config)],
      }));
      return config;
    },
  },
});

Keep step imports consistent:

const { Given, When, Then } = require('@badeball/cypress-cucumber-preprocessor/steps');

Bundler choices

Bundler Use it when Trade-off
esbuild You want the documented default and a small setup Requires the esbuild preprocessor package
Browserify Your Cypress project already has a Browserify pipeline More wiring for TypeScript and modern ESM behavior
Webpack Your application already centralizes transforms in Webpack More configuration and potentially slower startup

Changing bundlers does not fix a missing npm package or an invalid TypeScript resolution mode. First verify installation and imports, then align the preprocessor with the bundler your project actually uses.

Configure custom step-definition globs

If your steps live somewhere else, configure stepDefinitions in .cypress-cucumber-preprocessorrc.json:

{
  "stepDefinitions": [
    "cypress/e2e/**/*.ts",
    "cypress/steps/**/*.ts",
    "packages/*/cypress/steps/**/*.ts"
  ]
}

You can place equivalent configuration in package.json under the package’s configuration key. Keep globs narrow enough to avoid loading duplicate definitions. If two files define the same sentence, Cypress may report ambiguous matches even though module resolution is fixed.

Diagnostic checklist

  1. Run npm ls @badeball/cypress-cucumber-preprocessor. It should resolve from the package where Cypress runs.
  2. Open package.json and confirm the dependency is present under devDependencies.
  3. Search for old imports:
rg "cypress-cucumber-preprocessor|@badeball/cypress-cucumber-preprocessor" .
  1. Confirm every step import uses the scoped name.
  2. Confirm specPattern includes **/*.feature.
  3. Confirm setupNodeEvents awaits the plugin, installs the bundler, and returns config.
  4. Confirm step files match the configured globs.
  5. Restart Cypress and your editor’s TypeScript server after changing package exports or tsconfig.json.

Common errors and fixes

“Cannot find module” persists after npm install

Cause: Cypress is launched from a workspace root different from the package where the dependency was installed, or the install is incomplete.

Fix: Run the install in the same workspace that owns cypress.config.ts. If the lockfile is authoritative, remove the incomplete node_modules directory and reinstall from the lockfile:

rm -rf node_modules
npm ci

Use the equivalent clean-install command for your package manager and commit the resulting lockfile only when your normal repository workflow requires it.

TypeScript shows TS2307 but Cypress runs

Cause: The editor’s TypeScript resolver does not understand conditional exports.

Fix: Set moduleResolution to node16, reload the editor window, and restart the TypeScript server. If the project cannot change resolution, use the documented paths fallback.

Feature files are not listed by Cypress

Cause: The config still uses a JavaScript spec pattern such as cypress/e2e/**/*.cy.ts.

Fix: Set specPattern: '**/*.feature' in the E2E config. Check that the feature extension is lowercase and that the file is inside the Cypress project directory.

“Step implementation missing” after the import works

Cause: The step file is outside the default search paths, has a nonmatching extension, or its wording differs from the Gherkin sentence.

Fix: Move it under cypress/e2e or cypress/support/step_definitions, or add an explicit stepDefinitions glob. Then compare punctuation, parameters, and capitalization in the feature and definition.

Duplicate or ambiguous step definitions

Cause: A broad custom glob loads both a legacy file and a new file.

Fix: Narrow the glob, remove the duplicate definition, and keep one canonical implementation for each sentence pattern.

“Cannot use import statement outside a module”

Cause: The selected bundler and module settings disagree.

Fix: Use the documented esbuild integration consistently, or configure the Browserify/Webpack adapter for your existing pipeline. Do not combine CommonJS and ESM entry points arbitrarily in the same preprocessor chain.

Works locally, fails in CI

Cause: CI is using a different Node version, a production-only install, a different working directory, or a stale cache.

Fix: Install development dependencies in the Cypress job, use the lockfile, print node --version and npm ls @badeball/cypress-cucumber-preprocessor, and make the Cypress command run from the package containing the config.

Monorepos and workspaces

In a monorepo, package resolution starts from the package that owns the Cypress config and its dependency graph. Put the preprocessor in that package’s devDependencies, not only in an unrelated application package. If workspaces hoist dependencies, verify the package is still available when CI uses a focused install. Keep feature files, step globs, and config paths relative to the Cypress package so moving the repository root does not change what is discovered.

Performance and reliability notes

  • Esbuild generally keeps preprocessing configuration small and avoids carrying a full application bundle into every feature file.
  • Broad step globs increase discovery work and can load duplicate files. Prefer a few explicit directories.
  • Use one lockfile-driven install in CI and cache dependencies by lockfile hash. A cache hit with missing files is worse than a clean install, so invalidate caches when package versions change.
  • Keep plugin registration inside setupNodeEvents and return the resulting config. This makes behavior deterministic between interactive and headless runs.
  • Run a small feature smoke test after dependency upgrades. Conditional-export changes can affect editor diagnostics even when the browser test itself still starts.

Or skip the browser setup

If your goal is to capture a page image for documentation, visual checks, or an AI workflow rather than run a browser test, ScreenshotNeo provides a single screenshot request. The API accepts a URL and returns PNG, JPEG, WebP, or PDF output; its developer docs list the options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. An MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Do I need to import from /steps?

No. You can use other package entry points, but /steps is the standard import for the built-in Given, When, and Then helpers.

Can I keep the old unscoped package?

Do not mix it with the Badeball package. Remove old imports and migrate one package consistently.

Is node16 required for JavaScript?

No. It is primarily a TypeScript resolution fix. JavaScript still requires the maintained package and correct Cypress plugin setup.

Why does reinstalling sometimes fix the issue?

An interrupted install or stale workspace cache can leave package files missing even though the lockfile lists them. A clean lockfile install restores the expected exports.