If you have ever bounced between import and require, or puzzled over .mjs and .cjs files, you are not alone. Modern JavaScript projects often juggle bundlers, Node versions, and browser targets, which makes module formats feel more complicated than they need to be.<\/p>\n\n\n\n
Hi folks,<\/em> What are the best practices for setting up ESM, handling dynamic imports, and interop with CommonJS modules? Any tips on pitfalls to avoid would be appreciated.<\/em><\/p>\n\n\n\n ESM stands for ECMAScript Modules. It is the standardized module system for JavaScript, supported natively by modern browsers and Node. ESM uses the import and export keywords, enables static analysis for better tree-shaking and performance, and encourages clearer dependency graphs.<\/p>\n\n\n\n In contrast, CommonJS is an older effort to create a standardized module system, but primarily for server-side JavaScript. These are synchronous and can<\/em> be used by ESM, but ESM modulus can\u2019t consume CommonJS ones.<\/p>\n\n\n\n Modern browsers can load ESM directly using a script tag with type=”module”.<\/p>\n\n\n You can also use dynamic imports to lazy-load code:<\/p>\n\n\n Node supports ESM in two main ways:<\/p>\n\n\n\n Sometimes you must mix ESM and CJS.<\/p>\n\n\n\n After you set up ESM in your app, you can import modern SDKs directly and keep your bundle lean. For example, in a front-end project you can use Cloudinary\u2019s ESM-friendly URL Generation library to build optimized image URLs at runtime, then let your bundler tree-shake unused parts.<\/p>\n\n\n
I keep seeing ESM mentioned in docs and configs and I am confused about when to use it. What is ESM in JavaScript? How is it different from CommonJS? I am building a full-stack app and want to use imports in both the browser and Node.<\/em><\/p>\n\n\n\nAnswer:<\/h2>\n\n\n\n
Key characteristics of ESM<\/h3>\n\n\n\n
\n
import<\/code> and export<\/code> instead of require<\/code> and module.exports<\/code>.<\/li>\n\n\n\nESM in the browser<\/h3>\n\n\n\n
<script<\/span> type<\/span>=\"module\"<\/span>><\/span>\n\u00a0 import<\/span> { greet } from<\/span> '.\/utils.js'<\/span>;\n\u00a0 greet('world'<\/span>);\n<\/span><\/script<\/span>><\/span><\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n\/\/ Lazy-load a heavy module only when needed<\/span>\nconst<\/span> { heavyFeature } = await<\/span> import<\/span>('.\/heavy.js'<\/span>);\nheavyFeature();<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\nESM in Node<\/h3>\n\n\n\n
\n
\"type\": \"module\"<\/code> in package.json, then .js files are treated as ESM.<\/li>\n\n\n\n\/\/ package.json<\/span>\n{\n\u00a0 \"type\"<\/span>: \"module\"<\/span>\n}\n\n\/\/ src\/main.js<\/span>\nimport<\/span> fs from<\/span> 'node:fs\/promises'<\/span>;\nimport<\/span> { greet } from<\/span> '.\/utils.js'<\/span>;\n\nconsole<\/span>.log(await<\/span> fs.readFile('.\/README.md'<\/span>, 'utf8'<\/span>));\ngreet('Node ESM'<\/span>);<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\nInterop with CommonJS<\/h3>\n\n\n\n
\n
\/\/ ESM file that needs a CJS module<\/span>\nimport<\/span> { createRequire } from<\/span> 'node:module'<\/span>;\nconst<\/span> require<\/span> = createRequire(import<\/span>.meta.url);\nconst<\/span> cjsLib = require<\/span>('.\/legacy.cjs'<\/span>); \/\/ CommonJS module<\/span>\ncjsLib.run();<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n\n
\/\/ CommonJS file<\/span>\n(async<\/span> () => {\n\u00a0 const<\/span> { greet } = await<\/span> import<\/span>('.\/utils.js'<\/span>);\n\u00a0 greet('from CJS'<\/span>);\n})();<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\nCommon pitfalls<\/h3>\n\n\n\n
\n
__dirname<\/code> and<\/strong> __filename<\/code>:<\/strong> Not available in ESM. Use import.meta.url<\/code> with URL APIs.<\/li>\n\n\n\nimport<\/code> with an assertion in newer runtimes.<\/li>\n<\/ul>\n\n\nimport<\/span> config from<\/span> '.\/config.json'<\/span> assert { type<\/span>: 'json'<\/span> };<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\nPerformance and bundling tips<\/h3>\n\n\n\n
\n
Quick example – authoring and consuming ESM<\/h3>\n\n\n
\/\/ utils.js<\/span>\nexport<\/span> function<\/span> greet<\/span>(name<\/span>) <\/span>{\n\u00a0 console<\/span>.log(`Hello, ${name}<\/span>!`<\/span>);\n}\nexport<\/span> const<\/span> VERSION = '1.0.0'<\/span>;\n\n\/\/ app.js<\/span>\nimport<\/span> { greet, VERSION } from<\/span> '.\/utils.js'<\/span>;\ngreet('ESM'<\/span>);\nconsole<\/span>.log(VERSION);<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\nUsing ESM with Cloudinary for media delivery<\/h3>\n\n\n\n
\/\/ In the browser with ESM<\/span>\nimport<\/span> { Cloudinary } from<\/span> '@cloudinary\/url-gen'<\/span>;\nimport<\/span> { fill } from<\/span> '@cloudinary\/url-gen\/actions\/resize'<\/span>;\nimport<\/span> { format } from<\/span> '@cloudinary\/url-gen\/actions\/delivery'<\/span>;\n\nconst<\/span> cld = new<\/span> Cloudinary({ cloud<\/span>: { cloudName<\/span>: 'demo'<\/span> }});\nconst<\/span> img = cld.image('samples\/landscapes\/nature'<\/span>)\n\u00a0 .resize(fill().width(600<\/span>).height(400<\/span>))\n\u00a0 .delivery(format('auto'<\/span>));\n\ndocument<\/span>.getElementById('hero'<\/span>).src = img.toURL();<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n