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.

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-preprocessoris 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_modulesis incomplete or your editor has cached an older package layout.
Fastest supported fix
- 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.

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 configpreserves 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:

{
"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
- Run
npm ls @badeball/cypress-cucumber-preprocessor. It should resolve from the package where Cypress runs. - Open
package.jsonand confirm the dependency is present underdevDependencies. - Search for old imports:
rg "cypress-cucumber-preprocessor|@badeball/cypress-cucumber-preprocessor" .
- Confirm every step import uses the scoped name.
- Confirm
specPatternincludes**/*.feature. - Confirm
setupNodeEventsawaits the plugin, installs the bundler, and returnsconfig. - Confirm step files match the configured globs.
- 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
setupNodeEventsand 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.


