ESM, CommonJS, and browser modules fail to load

Understand the likely causes

• Typical causes are a classic browser script containing module syntax, a bare package name without browser resolution support, an HTML fallback returned for JavaScript, wrong MIME or cross-origin policy, and incompatible CommonJS/ESM assumptions. A cycle or top-level exception belongs to evaluation or initialization, not necessarily network retrieval.

1. Identify the executing host and module mode

Record whether the code runs in a browser, a Node process, or a build tool. In a browser, use a module script for static import/export syntax and serve through a controlled HTTP origin for a realistic loading check. In Node, inspect the file extension and nearest package configuration that determine module interpretation. require and module.exports are CommonJS facilities, not universal JavaScript globals. Do not change several settings at once, because a second failure can hide which initial assumption was wrong.

2. Inspect the exact resource and resolution path

For browser imports, inspect the final requested URL, status, MIME, and a small body preview. A 200 response beginning with HTML often means a fallback route served the application page instead of the module. Relative specifiers resolve from the importing module URL, not an imagined project root. Bare names need an import map or configured build output. Cross-origin failure needs a correct server policy; disabling browser protections is not a contextual application fix. Keep all diagnosis on owned local resources or read-only authorized endpoints.

3. Verify the export contract independently

Check named versus default exports and the actual version of the loaded dependency. The self-contained example tests a named ESM export with a local data URL; it does not fetch a package or prove the project server configuration. If linking succeeds but top-level execution throws, isolate that execution error and inspect initialization order or cycles. Avoid importing a mutable global merely to break a cycle; separating shared definitions or using an explicit start operation usually provides a clearer dependency direction.

const source = "export function double(value) { return value * 2; }";
const namespace = await import("data:text/javascript," + encodeURIComponent(source));
console.log(typeof namespace.double);
console.log(namespace.double(4));

function
8

4. Repair one boundary rather than mixing loaders

Choose the project’s module contract and adapt at an intentional boundary when CommonJS interoperation is necessary. Consult the actual Node version’s rules rather than assuming named imports from every CommonJS package behave identically. A browser cannot load a Node-only file-system API merely because a bundler accepts its syntax. Keep portable domain modules separate from host adapters, and remove stale build outputs or incorrect paths through the project’s documented build process. Do not edit installed dependency files as the permanent repair.

Keep it from recurring

• Document module mode, explicit file/specifier conventions, browser serving assumptions, and supported host versions. Keep import graphs directional and initialization effects visible. Include one clean entry-point smoke check so a passing pure unit test does not conceal a broken loader or incorrect static-resource fallback.