vitest-dev/vitest · error · Error

Vitest cannot be imported in a CommonJS module using require

Error message

Vitest cannot be imported in a CommonJS module using require(). Please use "import" instead.

If you are using "import" in your source code, then it's possible it was bundled into require() automatically by your bundler. In that case, do not bundle CommonJS output since it will never work with Vitest, or use dynamic import() which is available in all CommonJS modules.

What it means

Vitest is published as an ESM-only package ("type": "module" in packages/vitest/package.json). Its package.json `exports` map deliberately points the `require` condition to packages/vitest/index.cjs, whose entire body is `throw new Error(...)` (index.cjs:1-5). This is an intentional guardrail: requiring 'vitest' from a CommonJS module cannot work because Vitest relies on ESM-only features (top-level import.meta, dynamic import, the Vite module graph), so instead of a cryptic ERR_REQUIRE_ESM it throws a message explaining the cause and the fix.

Source

Thrown at packages/vitest/index.cjs:1

throw new Error(
  'Vitest cannot be imported in a CommonJS module using require(). Please use "import" instead.'
  + '\n\nIf you are using "import" in your source code, then it\'s possible it was bundled into require() automatically by your bundler. '
  + 'In that case, do not bundle CommonJS output since it will never work with Vitest, or use dynamic import() which is available in all CommonJS modules.',
)

View on GitHub (pinned to d568f8ce37)

Solutions

1. Use ESM: `import { ... } from 'vitest'` in a .mjs/.js (with "type":"module") or .ts file.
2. If you are in a CommonJS module and cannot migrate, use dynamic import: `const { vitest } = await import('vitest')`.
3. Stop bundling Vitest into CommonJS output — configure your bundler to emit ESM, or mark 'vitest' as external.
4. Rename the requiring file to .mjs or .ts (and set the package/module config to ESM) so Node resolves it as ESM.

Example fix

// before — tools/setup.cjs (CommonJS)
const { describe, it, expect } = require('vitest')

// after — option A: convert to ESM (tools/setup.mjs)
import { describe, it, expect } from 'vitest'

// after — option B: dynamic import from CJS
async function load() {
  const vitest = await import('vitest')
  return vitest
}

// Detect a CJS context before attempting to load Vitest, and use dynamic
// import() (always available in CJS) instead of require().
function isCommonJS() {
  return typeof module !== 'undefined' && !!module.exports
}
async function loadVitest() {
  if (isCommonJS()) {
    // require('vitest') would hit index.cjs and throw; dynamic import is safe.
    return await import('vitest')
  }
  return await import('vitest')
}

// Helper for bundlers: mark 'vitest' external so it is never rewritten to a require().
// rollup.config.js / vite.config.ts (build side)
// export default {
//   external: ['vitest', /^vitest\//],
// }

When it happens

Trigger: Calling `require('vitest')` (or `require('vitest/...')`) from a .cjs file; a bundler configured to output CommonJS that statically bundles a Vitest import into a require() call; a tool (eslint plugin, jest config, ts-node with CommonJS) that loads Vitest via require; a Jest setup file that tries to require Vitest APIs.

Common situations: Configuring ESLint/Jest/ts-node in CommonJS mode and trying to `require('vitest/...')` for types or globals; a bundler (older webpack/rollup config, tsup with format:cjs) emitting CJS output that bundles the Vitest import; migrating a Jest project and leaving a `require('vitest')` in jest.config.cjs; a .cjs config helper importing Vitest helpers.

Related errors

• require() is not supported in virtual modules. Trying to cal
• Cannot parse the module format of '${url}' because "module.f
• Cannot spy on export "${String(key)}". Module namespace is n
• Runner must export a default function, but got ${typeof mod.
• invalid diff config file ${config.diff}. Must have a default

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/2e1aef4d54dd9c00.json. Report an issue: GitHub.