CommonJS vs ESM differences in Node.js - When to Use Which

The Big Idea

Discover why choosing the right module system can save you hours of debugging and confusion!

The Scenario

Imagine you have many JavaScript files in your Node.js project, and you need to share code between them. You try to manually copy and paste functions everywhere or write complex scripts to load files in the right order.

The Problem

Manually managing code sharing is confusing and error-prone. You might load files in the wrong order, cause naming conflicts, or struggle to reuse code efficiently. It slows down development and makes your project hard to maintain.

The Solution

CommonJS and ESM are two systems that let you easily import and export code between files. They handle loading and sharing automatically, so you can focus on writing your app instead of managing file dependencies.

Before vs After

✗ Before

const utils = require('./utils');
const data = utils.loadData();

✓ After

import { loadData } from './utils.js';
const data = loadData();

What It Enables

These module systems let you build clean, organized, and reusable code that works smoothly across your Node.js projects.

Real Life Example

Think of a recipe book where each recipe is a module. CommonJS and ESM help you pick and use recipes easily without rewriting them every time you cook.

Key Takeaways

Manual code sharing is slow and error-prone.

CommonJS and ESM automate code importing and exporting.

They help keep projects organized and maintainable.

Practice

1. Which syntax is used to import modules in CommonJS in Node.js?

easy

A. const module = require('module')

B. import module from 'module'

C. module.import('module')

D. load('module')

Solution

1. Step 1: Understand CommonJS import syntax

   CommonJS uses the require function to import modules.

2. Step 2: Compare with other options

   Options A, B, and C are not valid CommonJS import syntax; B is ESM syntax.

3. Final Answer:

   const module = require('module') -> Option A

4. Quick Check:

   CommonJS imports use require() [OK]

Hint: CommonJS uses require(), ESM uses import [OK]

Common Mistakes:

• Confusing ESM import syntax with CommonJS
• Using import in CommonJS files
• Trying to use module.import() which doesn't exist

2. Which of the following is the correct way to export a function in ESM syntax?

easy

A. export = function() {}

B. module.exports = function() {}

C. exports.function = function() {}

D. export default function() {}

Solution

1. Step 1: Identify ESM export syntax

   ESM uses export default to export a default function or value.

2. Step 2: Eliminate CommonJS and invalid options

   module.exports = function() {} and C are CommonJS exports; D is invalid syntax.

3. Final Answer:

   export default function() {} -> Option D

4. Quick Check:

   ESM default export uses export default [OK]

Hint: ESM exports use export default or named export [OK]

Common Mistakes:

• Using module.exports in ESM files
• Trying to use export = which is invalid in ESM
• Confusing exports.function with ESM named exports

3. Given this CommonJS code, what will be the output?

const message = require('./message');
console.log(message);

And the file message.js contains:

module.exports = 'Hello from CommonJS';

medium

A. 'Hello from CommonJS'

B. undefined

C. SyntaxError

D. ReferenceError

Solution

1. Step 1: Understand module.exports in CommonJS

   The file exports a string 'Hello from CommonJS' using module.exports.

2. Step 2: Import and log the exported value

   The require call imports the string, so console.log prints it.

3. Final Answer:

   'Hello from CommonJS' -> Option A

4. Quick Check:

   CommonJS require returns module.exports value [OK]

Hint: require() returns module.exports value [OK]

Common Mistakes:

• Expecting require to return an object by default
• Confusing with ESM import behavior
• Thinking require throws error without .js extension

4. What is wrong with this ESM import statement in a Node.js file?

const fs = require('fs');

medium

A. Missing semicolon at the end

B. require is not defined in ESM modules

C. fs module cannot be imported in Node.js

D. Should use import fs from 'fs' instead

Solution

1. Step 1: Identify module system used

   The code uses require which is CommonJS syntax, but in ESM modules, require is not available.

2. Step 2: Understand ESM import rules

   ESM modules must use import statements; require is undefined.

3. Final Answer:

   require is not defined in ESM modules -> Option B

4. Quick Check:

   require() undefined in ESM [OK]

Hint: require() is undefined in ESM modules [OK]

Common Mistakes:

• Thinking require works in ESM without extra setup
• Confusing missing semicolon as error
• Believing fs cannot be imported in Node.js

5. You want to write a Node.js module that can be imported both by CommonJS and ESM users without errors. Which approach is best?

hard

A. Use module.exports and add a separate export default for ESM

B. Write only CommonJS syntax and use dynamic import() in ESM

C. Use a dual package approach with conditional exports in package.json

D. Write only ESM syntax and rename file to .mjs

Solution

1. Step 1: Understand compatibility challenges

   CommonJS and ESM have different import/export systems, so a single file often can't serve both seamlessly.

2. Step 2: Use Node.js dual package support

   Node.js supports conditional exports in package.json to provide separate entry points for CommonJS and ESM consumers.

3. Step 3: Evaluate other options

   Use module.exports and add a separate export default for ESM mixes syntaxes which doesn't work reliably, C requires dynamic import in consumers, D limits to ESM-only.

4. Final Answer:

   Use a dual package approach with conditional exports in package.json -> Option C

5. Quick Check:

   Dual package conditional exports solve CommonJS/ESM compatibility [OK]

Hint: Use package.json conditional exports for dual support [OK]

Common Mistakes:

• Trying to mix module.exports and export default in one file
• Using only .mjs files limits CommonJS users
• Relying on dynamic import() without package config