DEV Community

Cover image for TL;DR CommonJS vs ESM
Abbey Perini
Abbey Perini

Posted on โ€ข Edited on

33 1

TL;DR CommonJS vs ESM

In a Node.js project, you're likely to run into both CommonJS and ESM modules. Here's how to tell these module types apart at a glance.

CommonJS

CommonJS modules were part of Node.js when it was written in 2009. They run synchronously. Imports and exports are resolved and scripts are executed dynamically at runtime.

CommonJS uses __filename, __dirname, and NODE_PATH variables. ESM does not.

ESM

ECMAScript modules (ESM) or ES Modules were introduced in 2015 with JavaScriptES6 (also known as ECMAScript 2015 or ECMAScript 6). They are asynchronous. Imports and exports are resolved statically at parse time. The ESM module loader then downloads and parses scripts. Finally, the script executes.

ESM uses top-level await (await in a file outside an async function()). CommonJS does not.

Package.json

CommonJS:

"type": "commonjs"
Enter fullscreen mode Exit fullscreen mode

ESM:

"type": "module"
Enter fullscreen mode Exit fullscreen mode

Node.js throws an error for ESM modules without "type": "module", but I have yet to see a package.json with "type": "commonjs" in the wild.

Imports

CommonJS:

var module = require('file path');
Enter fullscreen mode Exit fullscreen mode

ESM:

import defaultStuff, { namedStuff } from 'file path';
Enter fullscreen mode Exit fullscreen mode

Exports

CommonJS:

// default
module.exports =

// default read-only
exports =

// named
module.exports.name =

// named read-only
exports.name =
Enter fullscreen mode Exit fullscreen mode

ESM:

// default
export default name

// named
export name
Enter fullscreen mode Exit fullscreen mode

File Extensions

Node.js will treat .js and .ts as CommonJS modules by default.

CommonJS uses .cjs for JavaScript and .cts for TypeScript.

ESM uses .mjs for JavaScript and .mts for TypeScript.

Runtime Environments

CommonJS is supported in all versions of Node.js.

ESM is supported in browsers and Node.js v12 or higher.

Strict Mode

CommonJS needs use strict at the top of the file.

ESM uses strict mode by default.

This

In CommonJS modules, this points at exports.

In ES modules, this is undefined.

Conclusion

At this point, I've upgraded a package and gotten an error like "ES Modules not supported" or "[module] is a CommonJS module, which may not support all module.exports as named exports" a few times. While troubleshooting, the search results I got were guides on how to write these modules or treatises on which one is better. This is the summary I wish I had before I had to jump down a rabbit hole just to understand an error.

Image of Timescale

๐Ÿš€ pgai Vectorizer: SQLAlchemy and LiteLLM Make Vector Search Simple

We built pgai Vectorizer to simplify embedding management for AI applicationsโ€”without needing a separate database or complex infrastructure. Since launch, developers have created over 3,000 vectorizers on Timescale Cloud, with many more self-hosted.

Read more

Top comments (3)

Collapse
 
Sloan, the sloth mascot
Comment deleted
Collapse
 
manuartero profile image
Manuel Artero Anguita ๐ŸŸจ โ€ข โ€ข Edited
Comment hidden by post author
Collapse
 
webreflection profile image
Andrea Giammarchi โ€ข
Comment hidden by post author

Some comments have been hidden by the post's author - find out more

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more