JavaScript Modules (ESM/CJS) Cheat Sheet

// math.jsexport const PI = 3.14159;export function add(a, b) { return a + b; }export default function multiply(a, b) { return a * b; }// app.jsimport multiply, { PI, add } from "./math.js";   // Default + named importsimport * as math from "./math.js";                // Namespace importexport { add as sum };                             // Re-export with renameexport * from "./math.js";                          // Re-export everything// Note: ESM import paths require file extensions in Node.js (./math.js, not ./math)

// math.jsconst PI = 3.14159;function add(a, b) { return a + b; }module.exports = { PI, add };// or: module.exports.add = add;// or a single default-like export: module.exports = add;// app.jsconst { PI, add } = require("./math.js");const math = require("./math.js");    // Whole module object// require() is synchronous and can be called conditionally/anywhere in the fileif (process.env.DEBUG) {  const debug = require("./debug.js");}

// package.json{  "name": "my-app",  "type": "module",  "main": "index.js"}// "type": "module"    -> .js files are treated as ESM// "type": "commonjs"  (default) -> .js files are treated as CJS// Use .mjs to force ESM and .cjs to force CJS regardless of "type"

// Importing a CJS module from ESM: works, module.exports becomes the default exportimport pkg from "./legacy-cjs-module.js";const { someFn } = pkg;// Dynamic import works in both ESM and CJS, always returns a Promiseasync function load() {  const mod = await import("./math.js");  mod.add(1, 2);}// require()-ing an ESM file from CJS throws --// ESM cannot be require()'d directly, use dynamic import() instead

// config.js (ESM only -- top-level await is a SyntaxError in CJS)const response = await fetch("https://api.example.com/config");export const config = await response.json();// app.jsimport { config } from "./config.js";// The engine suspends evaluation of app.js until config.js's top-level await settlesconsole.log(config);// Multiple sibling modules with top-level await run concurrently where possible,// but a chain of imports awaiting each other serializes -- watch for slow startup

{  "name": "my-lib",  "type": "module",  "exports": {    ".": {      "import": "./dist/index.mjs",      "require": "./dist/index.cjs",      "types": "./dist/index.d.ts"    },    "./plugin": "./dist/plugin.mjs",    "./package.json": "./package.json"  }}// Any subpath NOT listed here becomes unimportable from outside the package --// e.g. require("my-lib/dist/internal.js") throws ERR_PACKAGE_PATH_NOT_EXPORTED// even though the file physically exists on disk. This is "encapsulation".

// --- CJS: a.js and b.js require each other ---// a.jsconst b = require("./b.js");module.exports.value = "from a";console.log("b.value at require time:", b.value);   // often undefined -- b.js was mid-execution// --- ESM: a.mjs and b.mjs import each other ---// a.mjsimport { value as bValue } from "./b.mjs";export const value = "from a";console.log("b value:", bValue);   // TDZ error if accessed before b.mjs finishes initializing,                                     // but once both finish, bindings stay LIVE and stay in sync// ESM resolves the circular graph via hoisted bindings that update automatically as// the source module's exported variable changes -- CJS instead copies a value once.

// Static import with an import attribute (Node 18.20+/22+, replaces the older "assert" syntax)import config from "./config.json" with { type: "json" };// Dynamic equivalentconst { default: config2 } = await import("./config.json", {  with: { type: "json" },});// Omitting the attribute throws:// TypeError [ERR_IMPORT_ATTRIBUTE_MISSING]: Module needs an import attribute of "type: json"// CJS has no equivalent restriction -- require("./config.json") just works,// which is one more reason JSON imports behave differently across the two systems.