{"id":"2e1aef4d54dd9c00","repo":"vitest-dev/vitest","slug":"vitest-cannot-be-imported-in-a-commonjs-module-usi","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/vitest/index.cjs","lineNumber":1,"sourceCode":"throw new Error(\n  'Vitest cannot be imported in a CommonJS module using require(). Please use \"import\" instead.'\n  + '\\n\\nIf you are using \"import\" in your source code, then it\\'s possible it was bundled into require() automatically by your bundler. '\n  + '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.',\n)\n","sourceCodeStart":1,"sourceCodeEnd":6,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/vitest/index.cjs#L1-L6","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use ESM: `import { ... } from 'vitest'` in a .mjs/.js (with \"type\":\"module\") or .ts file.","If you are in a CommonJS module and cannot migrate, use dynamic import: `const { vitest } = await import('vitest')`.","Stop bundling Vitest into CommonJS output — configure your bundler to emit ESM, or mark 'vitest' as external.","Rename the requiring file to .mjs or .ts (and set the package/module config to ESM) so Node resolves it as ESM."],"exampleFix":"// before — tools/setup.cjs (CommonJS)\nconst { describe, it, expect } = require('vitest')\n\n// after — option A: convert to ESM (tools/setup.mjs)\nimport { describe, it, expect } from 'vitest'\n\n// after — option B: dynamic import from CJS\nasync function load() {\n  const vitest = await import('vitest')\n  return vitest\n}","handlingStrategy":"type-guard","validationCode":"// Detect a CJS context before attempting to load Vitest, and use dynamic\n// import() (always available in CJS) instead of require().\nfunction isCommonJS() {\n  return typeof module !== 'undefined' && !!module.exports\n}\nasync function loadVitest() {\n  if (isCommonJS()) {\n    // require('vitest') would hit index.cjs and throw; dynamic import is safe.\n    return await import('vitest')\n  }\n  return await import('vitest')\n}","typeGuard":"// Helper for bundlers: mark 'vitest' external so it is never rewritten to a require().\n// rollup.config.js / vite.config.ts (build side)\n// export default {\n//   external: ['vitest', /^vitest\\//],\n// }","tryCatchPattern":null,"preventionTips":["Configure your bundler to emit ESM output, or mark `vitest` (and `vitest/*`) as external so the import is preserved.","Prefer .mjs/.ts config files over .cjs when they reference Vitest APIs.","If you must stay CommonJS, always use `await import('vitest')` — it is available in every modern Node CJS module.","Add a CI grep for `require('vitest` across the repo to catch regressions before they ship."],"tags":["esm","commonjs","require","bundler","package-exports"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}