skip to content
Nikolas Barwicki - Javascript Blog Nikolas's Blog

CommonJS vs ES Modules: the shift from require to import

/ 14 min read

javascript

Introduction

The aim of this article is to shed light on the intricacies of JavaScript’s module systems, focusing on the nuances that differentiate them. We will delve into the traditional require syntax associated with CommonJS modules, contrast it with the modern import syntax of ES Modules (ESM), and explore the significance of file extensions (.js vs. .mjs). Additionally, we will unravel the mysteries of the type property in package.json, discussing its impact on how JavaScript files are interpreted by runtime environments like Node.js.

Evolution of JavaScript Modules

The history of JavaScript modules is a testament to the language’s growth and the community’s ongoing efforts to address its limitations. Initially, JavaScript did not have a built-in module system. Developers relied on including multiple <script> tags in their HTML documents to load scripts. This approach was simple but fraught with challenges, including namespace pollution, dependency management headaches, and the lack of encapsulation.

From Script Tags to AMD

As web applications became more complex, the need for a more structured way to organize JavaScript code became evident. This led to the development of Asynchronous Module Definition (AMD). AMD was designed for asynchronous loading of modules, helping to improve web page performance by allowing non-blocking behavior. Tools like RequireJS popularized the AMD format, enabling developers to define modules and their dependencies in a more manageable way.

The Rise of CommonJS

However, AMD’s focus on asynchronous loading was not a perfect fit for all use cases, especially server-side development where modules could be loaded synchronously from the file system. This gap was filled by CommonJS, a module system initially designed for use in Node.js. CommonJS modules allowed for a simpler syntax and synchronous loading, making it ideal for server-side applications. The require function and module.exports became the backbone of module interaction in Node.js, fostering a rich ecosystem of packages on npm.

Emergence of ES Modules

The latest chapter in the evolution of JavaScript modules is the introduction of ES Modules (ESM), standardized in ECMAScript 2015 (ES6). ESM introduced the import and export syntax, bringing a native module system to JavaScript for the first time. Unlike CommonJS, ESM is designed to work both in the browser and on the server, offering static analysis benefits, tree shaking (elimination of unused code), and more efficient loading mechanisms.

Why the Evolution Matters

Understanding this evolution is crucial for today’s JavaScript developers for several reasons:

  • Cross-Environment Compatibility: Knowing the differences between module systems allows developers to write code that is compatible across different environments (e.g., Node.js, web browsers).
  • Performance Optimization: The static nature of ESM allows for optimizations like tree shaking, which can significantly reduce the size of web applications.
  • Future-Proofing Projects: As the JavaScript ecosystem continues to embrace ESM, understanding and adopting this standard can help ensure that projects remain maintainable and forward-compatible.
  • Community and Ecosystem Participation: A deep understanding of JavaScript modules enhances your ability to engage with and contribute to open-source projects, many of which are transitioning to or already using ESM.

The journey from script tags to ES Modules highlights not only the technical progression of JavaScript as a language but also the community’s commitment to addressing its challenges. For developers, staying abreast of these changes is not merely a matter of historical interest but a necessary step in mastering modern JavaScript development practices.

CommonJS and ES Modules: Key Differences

In the landscape of JavaScript modularity, two systems stand out: CommonJS (CJS) and ES Modules (ESM). Understanding the differences between these systems is pivotal for developers navigating the JavaScript ecosystem, especially when working across different environments like Node.js and the browser. Here’s a closer look at the key distinctions.

Syntax Differences

The most apparent difference between CommonJS and ES Modules is the syntax used for importing and exporting modules.

  • CommonJS: Utilizes the require() function for importing modules and module.exports or exports for exporting. This syntax is straightforward and familiar to many JavaScript developers, especially those with a background in Node.js.
// Importing with CommonJS
const express = require('express');

// Exporting with CommonJS
module.exports = function() {
  // Some functionality
};
  • ES Modules: Uses the import statement for importing and the export statement for exporting. This syntax is more declarative and supports importing and exporting multiple values, as well as renaming imports and exports.
// Importing with ES Modules
import express from 'express';

// Exporting with ES Modules
export function myFunction() {
  // Some functionality
};

Environment Usage

  • CommonJS: Predominantly used in Node.js for server-side development. CommonJS’s synchronous loading is well-suited for the server, where modules are loaded from the local filesystem, minimizing the impact of synchronous I/O operations.

  • ES Modules: Designed to be a universal module system for both browser and server-side JavaScript. ESM’s static structure allows for tree-shaking in build tools, leading to potentially smaller bundles for front-end applications. Modern browsers support ESM natively, and Node.js has added support for ES Modules in recent versions, albeit with some differences in implementation and file resolution.

Dynamic vs. Static Structure

  • CommonJS: Offers dynamic imports, meaning the require() statements can be conditionally called within functions or blocks of code. This dynamic nature provides flexibility but limits certain optimizations like tree shaking.

  • ES Modules: Are static, meaning the import and export statements must be at the top level of a module. This restriction allows for static analysis, enabling optimizations such as tree shaking and easier static analysis by tools and IDEs.

Implications for Developers

The choice between CommonJS and ES Modules affects various aspects of a JavaScript project, from its structure and build process to compatibility and performance optimizations. While CommonJS remains prevalent in Node.js environments, the broader JavaScript community is increasingly adopting ES Modules for its benefits in static analysis and cross-environment compatibility.

For developers, understanding these differences is crucial for making informed decisions about module structure, especially when working on projects that target both server-side and browser environments. Transitioning between module systems or maintaining code that utilizes both can be challenging, but with a clear grasp of the key differences and their implications, developers can navigate these complexities with greater confidence.

.js vs. .mjs: Significance and Usage

The introduction of ES Modules (ESM) brought not only a new syntax but also a new file extension to the JavaScript ecosystem: .mjs. This distinction between .js and .mjs files has implications for how modules are treated, especially in Node.js, and understanding these differences is vital for developers.

Purpose Behind .mjs

The .mjs extension explicitly signifies that a file should be treated as an ES Module. This differentiation became necessary due to Node.js’s existing support for CommonJS modules using the .js extension. Without a clear distinction, Node.js could not reliably determine how to interpret a given JavaScript file—whether as a CommonJS module or an ES Module.

How Node.js Treats .js and .mjs Files

  • .js Files: By default, Node.js treats .js files as CommonJS modules. This behavior aligns with Node.js’s historical use and ensures backward compatibility with the vast majority of existing JavaScript projects.

  • .mjs Files: Files with the .mjs extension are always treated as ES Modules by Node.js. This clear demarcation allows developers to use modern module syntax without ambiguity.

The Implications for Developers

The dual file extension system requires developers to be mindful of how they structure and name their module files, especially in projects that may use both module systems. Here are a few implications:

  • Explicitness and Clarity: Using .mjs can provide clarity, making it immediately apparent to other developers that the file is an ES Module. This explicitness can be especially helpful in mixed-codebase projects.

  • Configuration Simplicity: In projects where ES Modules are the standard, adopting the .mjs extension can simplify configuration by avoiding the need for additional setup in package.json or compiler/bundler settings to treat .js files as ESM.

  • Compatibility Considerations: While modern environments support .mjs, some tools or older environments may not. Developers need to consider their project’s target environments and toolchains when deciding whether to use .mjs.

Transitioning Between Extensions

Transitioning a project to use .mjs files or integrating .mjs files into an existing project can involve several steps, including updating build processes, ensuring compatibility with third-party tools, and potentially modifying import statements to reflect the new file extensions.

The type Property in package.json Explained

In the context of JavaScript modules and the evolving ecosystem, the type property in a project’s package.json plays a pivotal role in determining how Node.js interprets .js files. This property provides a way to set a default module system (CommonJS or ES Module) for JavaScript files in a project. Understanding and correctly setting this property is crucial for developers working with Node.js and JavaScript modules.

Understanding the type Field

The type field in package.json can have two possible values:

  • “commonjs”: This is the default behavior if the type field is not specified. With this setting, .js files are treated as CommonJS modules. This setting aligns with Node.js’s traditional module system and is backward compatible with the vast majority of Node.js projects.

  • “module”: When the type field is set to “module”, .js files are treated as ES Modules. This setting allows developers to use import and export syntax directly in .js files without needing to use the .mjs extension. This is particularly useful for projects that exclusively use ES Module syntax.

Implications for Developers

The inclusion of the type property provides flexibility but also requires careful consideration:

  • Project Configuration: The type setting impacts how all .js files in the project (or within the scope of the package.json file) are interpreted. Incorrectly setting this value can lead to module resolution errors or unexpected behavior.

  • Mixed Module Types: In projects where both CommonJS and ES Module files coexist, developers need to be mindful of the type setting. For example, if type is set to “module”, CommonJS files must use the .cjs extension to be correctly treated as CommonJS modules.

  • Compatibility and Tooling: While the type field is respected by Node.js and increasingly by tools in the JavaScript ecosystem, developers should verify compatibility with their toolchain, including bundlers, linters, and transpilers.

Practical Examples

Setting the type field in package.json:

{
  "type": "module"
}

This configuration tells Node.js to treat all .js files in the project as ES Modules. Conversely, setting it to "commonjs" would treat them as CommonJS modules.

Practical Guide to Using import and require

Navigating the distinctions between import and require in JavaScript is essential for developers working across different environments and module systems. This section provides a practical guide on when and how to use these two approaches for module importation, including considerations for dynamic imports, which serve as a bridge between CommonJS and ES Modules.

When to Use import

  • Static Importing in ES Modules: Use import for statically importing ES Modules (ESM). This syntax is ideal for front-end code and server-side JavaScript where ES Modules are supported. It allows for optimizations like tree-shaking and ensures static analysis tools can efficiently analyze dependencies.
// Importing a single export from a module
import { fetchData } from './dataFetcher.mjs';

// Importing the default export
import express from 'express';
  • Dynamic Imports in ES Modules: For cases where you need to conditionally or asynchronously load modules, ES Modules offer dynamic import syntax. This returns a promise, making it suitable for use in applications that require code splitting or lazy loading.
if (condition) {
  import('./module.mjs').then((module) => {
    module.doSomething();
  });
}

When to Use require

  • CommonJS Environments: require is the traditional way to import modules in Node.js applications and other CommonJS environments. It’s synchronous and straightforward, making it suitable for server-side applications where modules are loaded from the local filesystem.
const fs = require('fs');

const data = fs.readFileSync('/path/to/file.txt', 'utf8');
  • Conditional Imports: Although dynamic imports with import() are now supported in many environments, require can still be used for synchronous conditional importing in CommonJS modules.
let library;
if (condition) {
  library = require('library');
}

Bridging the Gap: Dynamic Imports

Dynamic imports (import()) provide a powerful mechanism for bridging the gap between CommonJS and ES Modules. They allow code to be loaded asynchronously and conditionally, fitting various use cases like lazy loading of modules or conditional loading based on runtime checks.

Practical Tips

  • Refactoring from CommonJS to ES Modules: When migrating a project, start by converting module syntax from require to import. This may also involve renaming files to .mjs or adjusting the type property in package.json if you wish to use .js for ES Modules.

  • Mixing Module Systems: While mixing import and require in the same project is possible, it’s generally recommended to stick to one module system for consistency. If mixing is necessary, be clear about the boundaries and use dynamic imports to load CommonJS modules into ES Module code when possible.

  • Tooling and Transpilation: Modern JavaScript tooling often provides options to transpile ES Module syntax to CommonJS for compatibility with older environments. Tools like Babel and Webpack can be configured to handle both module types seamlessly.

Transitioning and Compatibility Strategies

As the JavaScript ecosystem steadily moves towards ES Modules (ESM) as the standard, many developers face the challenge of transitioning their projects from CommonJS (CJS) to ESM. This shift can enhance module management, enable tree shaking, and align projects with the evolving standards of web development. However, the transition requires careful planning and execution to avoid common pitfalls. Here are some strategies and tips for successfully transitioning from CJS to ESM, as well as maintaining compatibility within mixed module system projects.

Gradual Transition Approach

  1. Assess Your Project’s Dependencies: Before starting the transition, assess whether your project’s external dependencies support ESM. This step is crucial because a mix of CJS and ESM dependencies can complicate the transition.

  2. Start with Leaf Modules: Begin the transition with the “leaf” modules (modules that don’t depend on other modules within your project) and gradually work your way up to the “root” modules (modules that your application entry points depend on). This bottom-up approach minimizes disruption.

  3. Use Interoperability Features: Node.js provides interoperability features to import CJS modules into ESM and vice versa. Utilize import() to dynamically import CJS modules into ESM code, and use .cjs extensions or the package.json "type": "commonjs" declaration for CJS files that need to remain as such.

Ensuring Compatibility

  1. Dual Package Hazard: Be aware of the dual package hazard, where a package might be loaded twice in different forms (CJS and ESM), leading to bugs and inconsistencies. Avoid this by not mixing imports of the same package in different formats.

  2. Publishing Dual Packages: If you’re maintaining a library, consider publishing it as a dual package, supporting both CJS and ESM. This can be achieved by specifying both "main" (for CJS) and "module" (for ESM) fields in package.json, and carefully organizing your source files to ensure compatibility.

  3. Testing Across Environments: Test your project in all target environments (e.g., Node.js, browsers, bundlers) to ensure compatibility. Automated testing tools and continuous integration (CI) services can help streamline this process.

Avoiding Common Pitfalls

  1. Mixed Module Syntax: Avoid mixing CJS and ESM syntax within the same module, as it can lead to confusing behavior and compatibility issues. Stick to one module format per file.

  2. Dynamic Import Syntax: Remember that import() returns a promise. Ensure your code properly handles asynchronous loading, especially when refactoring from synchronous require() calls.

  3. Tooling Support: Ensure that your build tools, linters, and other development tools support ESM. Most modern tools do, but configurations might need to be updated.

Tips for Maintaining Compatibility

  1. Code Splitting and Lazy Loading: For web projects, use bundlers like Webpack or Rollup that support both CJS and ESM. They can help with code splitting and lazy loading, improving application performance.

  2. Transpilation for Legacy Environments: Use Babel or TypeScript to transpile ESM code to CJS for compatibility with older JavaScript environments that do not support ESM.

  3. Documentation and Team Communication: Clearly document your project’s module system and any interoperability considerations. Keep your team informed about the standards and practices you’re adopting for module usage.

Conclusion

The journey through the intricacies of JavaScript modules—from their evolution, differences between CommonJS and ES Modules, the significance of .js vs. .mjs extensions, to the strategic use of the type property in package.json, and practical guides for transitioning and compatibility—underscores the dynamic nature of JavaScript development. This exploration reveals not only the technical considerations but also the strategic decisions developers must make to ensure their projects are efficient, maintainable, and future-proof.