CommonJS vs ESM differences in Node.js - Hands-On Comparison

CommonJS vs ESM Differences in Node.js

📖 Scenario: You are building a simple Node.js project that uses modules to organize code. You want to understand the difference between CommonJS and ESM (ECMAScript Modules) by creating examples of each and seeing how to export and import functions.

🎯 Goal: Build two small modules: one using CommonJS syntax and one using ESM syntax. Then import and use these modules in separate main files to see how the syntax differs.

📋 What You'll Learn

Create a CommonJS module file named mathCommonJS.js that exports a function add which adds two numbers.

Create an ESM module file named mathESM.mjs that exports a function multiply which multiplies two numbers.

Create a CommonJS main file named index-cjs.js that imports and uses the add function from the CommonJS module and an ESM main file named index-esm.mjs that imports and uses the multiply function from the ESM module.

Use require() to import the CommonJS module and import statement to import the ESM module.

Ensure the project runs correctly with Node.js 20+.

💡 Why This Matters

🌍 Real World

Node.js projects often use modules to organize code. Understanding CommonJS and ESM helps you work with different libraries and write modular code.

💼 Career

Many Node.js jobs require knowledge of module systems to maintain and build scalable applications. Knowing how to switch between CommonJS and ESM is valuable.

1

Create CommonJS module with add function

Create a file named mathCommonJS.js and write a function called add that takes two parameters a and b and returns their sum. Export this function using module.exports.

Node.js

// Your code here

Hint

Use module.exports = { add }; to export the function in CommonJS.

2

Create ESM module with multiply function

Create a file named mathESM.mjs and write a function called multiply that takes two parameters a and b and returns their product. Export this function using the export keyword.

Node.js

// Your code here

Hint

Use export function multiply(a, b) { ... } to export the function in ESM.

3

Import CommonJS module in index-cjs.js

Create a file named index-cjs.js. Import the add function from mathCommonJS.js using require(). Call add(2, 3) and store the result in a variable called sum. Log the sum to the console.

Node.js

// Your code here

Hint

Use const { add } = require('./mathCommonJS.js'); to import the CommonJS module.

4

Import ESM module in index-esm.mjs

Create a file named index-esm.mjs. Import the multiply function from mathESM.mjs using the import statement. Call multiply(4, 5) and store the result in a variable called product. Log the product to the console.

Node.js

// Your code here

Hint

Use import { multiply } from './mathESM.mjs'; to import the ESM module.

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