Node.js .js vs .mjs Files: What's the Difference?

• Introduction
• Step-by-Step Guide
• Code Example
• Additional Notes
• Summary
• Conclusion
• References

JavaScript initially lacked a formal module system, leading developers to use various workarounds. Node.js introduced CommonJS modules using the .cjs extension, while ECMAScript, the language standard, later established its own module system with the .mjs extension. This article clarifies the differences between .js, .mjs, and .cjs files in JavaScript, explaining their historical context, syntax, and how they are treated in Node.js and browsers. It also discusses the reasons behind the confusion surrounding these extensions and provides insights into when to use each one.

JavaScript has seen the rise of different module systems, leading to different file extensions like .js, .mjs, and .cjs. Here's a breakdown:

1. The Era Before Modules:

• Initially, JavaScript didn't have a built-in module system.
• Code was often organized into separate .js files.
• Developers used techniques like immediately invoked function expressions (IIFEs) to manage scope and avoid global namespace pollution.

2. CommonJS (.cjs): The Node.js Way

• Node.js, the JavaScript runtime for server-side development, adopted CommonJS as its module system.
• File Extension: .cjs files explicitly signal that they use CommonJS modules.
• Syntax:

  // module1.cjs
  module.exports = {
      sayHello: function() {
          console.log("Hello from module1!");
      }
  };
  
  // app.cjs
  const module1 = require('./module1.cjs');
  module1.sayHello(); 

3. ECMAScript Modules (.mjs): The Standard

• ECMAScript (the standardized language specification behind JavaScript) introduced its own module system (ESM).
• File Extension: .mjs files clearly indicate the use of ECMAScript modules.
• Syntax:

  // module2.mjs
  export function sayHi() {
      console.log("Hi from module2!");
  }
  
  // app.mjs
  import { sayHi } from './module2.mjs';
  sayHi();

4. The Role of .js

• Historically: .js was the default for all JavaScript files.
• In Node.js: Node.js treats .js files based on your project's configuration:
  • If "type": "module" is set in your package.json, .js files are treated as ECMAScript modules.
  • Otherwise, they are considered CommonJS modules.
• Browsers: Browsers generally don't rely on file extensions to determine module type. They use the <script> tag's type="module" attribute.

Why Use .mjs?

• Clarity: .mjs removes ambiguity, making it instantly clear that a file uses ECMAScript modules.
• Compatibility: Tools and environments designed for ESM can easily identify and work with .mjs files.

Why the Confusion?

• The transition to modules in JavaScript wasn't immediate or perfectly smooth.
• The dual existence of CommonJS and ESM, along with the flexible use of .js, can lead to confusion.

In Summary:

• .cjs: CommonJS modules (primarily Node.js).
• .mjs: ECMAScript modules (the standard, supported in modern environments).
• .js: Can be either CommonJS or ESM in Node.js, depending on configuration. In browsers, the <script> tag's type attribute is more relevant.

While .mjs promotes clarity, the best practice for your project depends on your environment, dependencies, and whether you prioritize explicitness or maintaining compatibility.

This code provides examples of using both CommonJS and ECMAScript modules in a JavaScript project. It showcases how to export and import functions using module.exports and require for CommonJS, and export and import for ECMAScript modules. The project is structured with separate files for each module system and a package.json file that defines the entry points and module type for Node.js. The code includes examples of running both CommonJS and ECMAScript modules using npm scripts.

This example demonstrates the different module systems in JavaScript.

Project Structure:

module-example/
├── module1.cjs
├── module2.mjs
├── app.cjs
├── app.mjs
└── package.json

1. CommonJS (module1.cjs, app.cjs):

// module1.cjs
module.exports = {
  sayHello: function() {
    console.log("Hello from module1.cjs!");
  }
};

// app.cjs
const module1 = require('./module1.cjs');
module1.sayHello(); // Output: Hello from module1.cjs!

2. ECMAScript Modules (module2.mjs, app.mjs):

// module2.mjs
export function sayHi() {
  console.log("Hi from module2.mjs!");
}

// app.mjs
import { sayHi } from './module2.mjs';
sayHi(); // Output: Hi from module2.mjs!

3. package.json (for Node.js):

{
  "name": "module-example",
  "version": "1.0.0",
  "description": "Example of different JavaScript module systems",
  "main": "app.cjs",
  "type": "module", // This line makes .js files ESM by default
  "scripts": {
    "start": "node app.cjs",
    "start-esm": "node app.mjs"
  }
}

Explanation:

• CommonJS: module.exports exports functionality, and require imports it.
• ECMAScript Modules: export keywords export functionality, and import keywords import it.
• package.json:
  • "type": "module" signifies that .js files in this project are treated as ECMAScript modules.
  • You can run the examples using npm start for CommonJS and npm run start-esm for ESM.

Important Notes:

• This example demonstrates the syntax and concepts. You'll need Node.js installed to run the code.
• Browsers handle modules differently. They rely on the <script type="module"> tag for ESM.
• The choice between CommonJS and ESM depends on your project's needs and environment.

General:

• The introduction of modules was a significant step towards making JavaScript more scalable and maintainable for larger projects.
• Understanding the differences between these module systems is crucial for both Node.js and front-end development.
• While .mjs offers clarity, using it might require adjustments in your build process or configuration, especially if you rely on tools that are not fully ESM-aware.

CommonJS:

• Designed primarily for synchronous loading, which aligns well with how Node.js reads files from the file system.
• Remains widely used in Node.js, especially in older projects.

ECMAScript Modules:

• Supported natively in modern browsers and increasingly in Node.js.
• Offers advantages like static analysis (analyzing code without execution) and potential for better optimization.
• Allows for both named and default exports, providing more flexibility in how you structure your code.

Choosing a Module System:

• New Node.js projects: Starting with ESM is generally recommended for new Node.js projects as it's the standard and offers modern features.
• Existing projects: Migrating an existing project from CommonJS to ESM can be complex, and the decision should be based on factors like the size of the project, dependencies, and the team's familiarity with ESM.
• Browser-based projects: For browser-based projects, using ESM with the <script type="module"> tag is the standard approach for working with modules.

Beyond File Extensions:

• The focus should be on understanding the underlying module systems (CommonJS and ESM) rather than just the file extensions.
• Tools and build processes often play a significant role in handling modules, and their configurations can impact how modules are resolved and loaded.

Future:

• While some challenges and points of confusion remain, the JavaScript ecosystem is moving towards greater adoption of ECMAScript modules as the standard.
• Understanding both module systems will continue to be important for working with a wide range of JavaScript projects and libraries.

This table summarizes the different JavaScript module file extensions and their uses:

Key Takeaways:

• .cjs and .mjs offer clarity by explicitly signaling the module system used.
• .js remains flexible but can lead to confusion due to its context-dependent interpretation in Node.js.
• The best practice depends on your project's needs. Consider your environment, dependencies, and the importance of clarity versus compatibility.

The evolution of JavaScript modules brought both progress and confusion. While the initial lack of a module system led to workarounds, Node.js introduced CommonJS (.cjs) and later, ECMAScript standardized modules (.mjs). This dual system, along with the flexible role of .js, often causes uncertainty. Choosing between .cjs and .mjs depends on your project's environment and priorities. While .mjs offers clarity and aligns with modern practices, .cjs remains relevant in Node.js. Ultimately, understanding these module systems is crucial for navigating the JavaScript landscape. As the language continues to evolve, embracing the standardized module system will lead to more maintainable and scalable JavaScript applications.

• Difference between .js and .mjs Extensions | by Mohit Gadhavi ... | Introduction: JavaScript has evolved significantly over the years, and with the introduction of different module systems, developers now…
• How to Differentiate Between Js and Mjs Files in Javascript | A basic guide to distinguish between .js and .mjs files in the context of Javascript.
• .js, .cjs and .mjs defference - DEV Community | CJS, MJS, and .JS are file extensions used to denote different types of JavaScript files. Here's the...
• The Difference Between MJS, CJS, and JS Files in Node.js | Coding ... | 👉 Here are some quick basics about the difference between .mjs, .cjs, and .js file extensions in Node.js.
• [AskJS] What's the current state for ".mjs" extension? Why is nobody ... | Posted by u/13MHz - 6 votes and 13 comments
• Difference Between .js and .mjs Files in JavaScript - Sadat Jubayer | The difference between .js and .mjs files in JavaScript, shedding light on how they impact our projects.
• MJS - Node.js ES Module Javascript File | Learn about what is a MJS file and APIs that can create and open MJS file.
• Not able to run .mjs files anymore in business central platform · Issue ... | Describe the bug As of version 4.0, almost all files in the npm package to have the .mjs format. However in some old web platforms, like MS Business Central this mime type extension cannot be used....
• From CommonJS to ES Modules: How to modernize your Node.js app | Modernize your Node.js project step by step and take advantage of ES Modules — The module system of the future.