Atlaslog / Field Notes / Build & deployment
Field note · Build & deployment
Importing a CommonJS package breaks the production build
Quick answer
The dev server runs fine, but `npm run build` aborts with a SyntaxError saying the module provides no export named 'default'. The package is UMD/CJS only, so the bundler's ESM interop and dependency pre-bundling decide whether a default export exists.
Symptom
- `npm run build` fails with `SyntaxError: The requested module '/node_modules/.vite/deps/proj4.js?v=9a1c3f2e' does not provide an export named 'default'`
- Webpack logs `WARNING in ./src/geo/transform.js "export 'default' (imported as 'proj4') was not found in 'proj4'`
- `npm run dev` serves the same page without any error, so the break only appears in the bundle
Checklist
- Read the package's package.json: a `main` entry with no `module` or `exports` field means CJS
- Run `node -e "const p=require('proj4'); console.log(typeof p, Object.keys(p).slice(0,5));"` and compare with the dynamic `import('proj4')` shape
- Search the build log for `commonjs` or `optimizeDeps` mentions
- Try a namespace import and read `.default` to confirm the interop assumption
- Rebuild after adding the package to `optimizeDeps.include`
Fix
Add `proj4` to `optimizeDeps.include` and set `build.commonjsOptions.transformMixedEsModules: true`, then use `import proj4 from 'proj4'`; when interop still fails, fall back to `import * as proj4Module from 'proj4'` plus `const proj4 = proj4Module.default || proj4Module`.
Code
error during build:
SyntaxError: The requested module '/node_modules/.vite/deps/proj4.js?v=9a1c3f2e'
does not provide an export named 'default'WARNING in ./src/geo/transform.js
"export 'default' (imported as 'proj4') was not found in 'proj4'
Watch out
- Writing named imports such as `import { transform } from 'proj4'`; CJS properties are not statically analyzable named exports
- Editing application code while ignoring the package format, which keeps failing until the optimizer handles the CJS entry
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). Importing a CommonJS package breaks the production build. https://www.jingweizhi.com/en/cookbook/esm-cjs-mixed.html (accessed 2026-11-03).