{"record":{"id":"92f0f668cce09148","repo":"remix-run/remix","slug":"commonjs-not-supported","errorCode":"COMMONJS_NOT_SUPPORTED","errorMessage":"CommonJS module detected: ${resolvedPath}. This module uses CommonJS (require/module.exports) which is not supported. Please use an ESM-compatible module.","messagePattern":"CommonJS module detected: (.+?)\\. This module uses CommonJS \\(require/module\\.exports\\) which is not supported\\. Please use an ESM-compatible module\\.","errorType":"error_code","errorClass":"AssetServerCompilationError","httpStatus":null,"severity":"error","filePath":"packages/assets/src/lib/scripts/transform.ts","lineNumber":254,"sourceCode":"      define: args.define ?? undefined,\n      minify: args.minify,\n      loaders: args.loaders,\n      moduleUrl: stableUrlPathname,\n      sourceMaps: args.sourceMaps ?? undefined,\n      target: args.target ?? undefined,\n    })\n\n    analysis.unresolvedImports = analysis.unresolvedImports.filter(\n      (unresolved) => !args.externalSet.has(getDisplayImportSpecifier(unresolved.specifier)),\n    )\n\n    if (mayContainCommonJSModuleGlobals(sourceText) && isCommonJS(analysis.rawCode)) {\n      throw createAssetServerCompilationError(\n        `CommonJS module detected: ${resolvedPath}. ` +\n          `This module uses CommonJS (require/module.exports) which is not supported. ` +\n          `Please use an ESM-compatible module.`,\n        {\n          code: 'COMMONJS_NOT_SUPPORTED',\n        },\n      )\n    }\n\n    let sourceMap = analysis.sourceMap\n      ? rewriteSourceMapSources(\n          analysis.sourceMap,\n          resolvedPath,\n          stableUrlPathname,\n          args.sourceMapSourcePaths,\n          sourceText,\n        )\n      : null\n\n    return {\n      ok: true,\n      tracking: {\n        trackedFiles,","sourceCodeStart":236,"sourceCodeEnd":272,"githubUrl":"https://github.com/remix-run/remix/blob/9696913134be3a4423513d2775f7b31d6917c049/packages/assets/src/lib/scripts/transform.ts#L236-L272","documentation":"During transform, the source is scanned with `mayContainCommonJSModuleGlobals` and then definitively checked with `isCommonJS(analysis.rawCode)`. If the module uses CommonJS constructs (require, module.exports, exports.x), the transform refuses it because the ESM-only asset pipeline cannot process it. This surfaces at build/serve time rather than silently producing broken output.","triggerScenarios":"transformModule on a .js/.ts module whose source contains `require(...)`, `module.exports`, `exports.foo = ...` (after a fast pre-check confirms CJS globals are present). Also triggered by transitive files pulled into the module graph that are CommonJS.","commonSituations":"Importing an npm package that ships CJS into the browser asset graph; legacy scripts copied into the source tree; code gated by `typeof module !== 'undefined'` still matching the heuristic; env-var style configs written in CJS; bundler-less setups that previously tolerated CJS.","solutions":["Convert the offending module to ESM: replace require() with import and module.exports/exports.x with export / export default","If it's a third-party dependency, find an ESM build of it or import it via a wrapper that the pipeline can handle, or vendor and convert it","Check the error's resolvedPath to identify exactly which module is CJS, then trace which import pulled it in","Remove dead CJS snippets (e.g. UMD boilerplate) from files you control"],"exampleFix":"// before\nconst path = require('node:path')\nmodule.exports = { helper }\n\n// after\nimport path from 'node:path'\nexport { helper }","handlingStrategy":"validation","validationCode":"import { mayContainCommonJSModuleGlobals } from './cjs-detect.ts' // or equivalent\nif (mayContainCommonJSModuleGlobals(sourceText) && isCommonJS(sourceText)) {\n  // exclude or convert this module before transform\n}","typeGuard":"function isEsmSource(source: string): boolean {\n  return !(mayContainCommonJSModuleGlobals(source) && isCommonJS(source))\n}","tryCatchPattern":"catch (e) { if (isAssetServerCompilationError(e) && e.code === 'COMMONJS_NOT_SUPPORTED') { /* convert module to ESM or swap dependency */ } else throw e }","preventionTips":["Prefer ESM-only dependencies; check package.json exports for \"import\" conditions","Add a lint/CI rule banning require()/module.exports in browser-bound source","Convert legacy scripts when vendoring them into the source tree"],"tags":["commonjs","esm","transform","assets"],"backgroundTag":"commonjs-in-esm-project","analyzedSha":"9696913134be3a4423513d2775f7b31d6917c049","analyzedAt":"2026-08-27T19:55:01.024Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}