Which Module Formats Should Your JavaScript Library Support?

As a web application grows and more features are added, modularizing the code improves readability and maintainability. In a basic web application, the application fetches and loads JavaScript files by having multiple 

 tags reference libraries from CDNs, such as 

, before the bundled application code. This approach involves manually ordering the 

For example, if you wanted to use a library like React in the browser (without any additional tooling, just plain HTML, CSS and JavaScript), then you would need to...

Continually adding more JavaScript files becomes more tricky because not only do you need to ensure that their dependencies precede them, but also that there are no naming collisions as a result of variables sharing the same global scope and overriding each other. With no native, built-in features for namespacing and modules in early versions of JavaScript language, different module formats have been introduced over the years to fill this void until the ES6 specification, which includes official syntax for writing modules via ECMAScript (ES6) modules.

Below, I'm going to provide a brief overview of the following module systems:

For developers, understanding each module system allows them to better determine which one best suits their applications' needs. For library authors, choosing the module systems their library should be compatible with depends on the environments where their intended users' applications run.

Immediately Invoked Function Expression (IIFE)

One of the earliest ways of exposing libraries in the web browser, 

 (IIFE) are anonymous functions that run right after being defined. 

(function () {
  // Module's Implementation Code
})();

Variables declared within the IIFE are scoped to the anonymous function, not to the global scope. This keeps variables inaccessible from outside the IIFE (restricts access only to the code within the IIFE) and prevents the pollution of the global scope.  

A common design pattern that leverages IIFEs is the 

, which creates a single object instance and namespaces code. This object serves as a single point of access to a specific group of functionality. For real-world examples, look no further than the 

Writing modules this way is convenient and supported by older browsers. In fact, you can safely concatenate and bundle together multiple files that contain IIFEs without worrying about naming and scoping collisions.

For modules with dependencies, you can pass those dependencies as arguments to the IIFE's anonymous function. If the dependency is of a primitive data type, then any changes made to the dependency in the global scope will not affect the IIFE module. If the dependency is an object, then any changes made to the dependency's properties in the global scope will affect the IIFE module, unless you destructure out the properties used in the IIFE module.

For the previous example, if we override the 

 method after running the IIFE, then subsequent calls to the module's 

If we modify the IIFE module to accept the 

 object as a dependency argument, then the module "captures a snapshot" of the object's properties via destructuring. Overriding these properties' values in later statements will have no affect on the module's methods.

Nevertheless, IIFE modules load synchronously, which means correctly ordering the module files is critical. Otherwise, the application will break. For large projects, IIFE modules can be difficult to manage, especially if you have many overlapping and nested dependencies.

 syntax for default and named exports respectively. Each file represents a module, and all variables local to the module are private since Node.js wraps the module within a function wrapper. 

const { PI, pow } = Math;

function calculateArea(radius) {
  return PI * pow(radius, 2);
}

module.exports = calculateArea;

(function(exports, require, module, __filename, __dirname) {
  const { PI, pow } = Math;

  function calculateArea(radius) {
    return PI * pow(radius, 2);
  }

  module.exports = calculateArea;
});

The module not only has its variables scoped privately to it, but it still has access to the globals 

 are module scoped and hold the file name and directory name of the module respectively. 

 syntax lets you import built-in Node.js or third-party modules locally installed and referenced in 

 (if supplied a module name) or custom modules (if supplied a relative path).

module.exports = {
  calculateArea: (radius) => {
    return Math.PI * Math.pow(radius, 2);
  },
  calculateCircumference: (radius) => {
    return 2 * Math.PI * radius;
  }
};

const { calculateArea, calculateCircumference } = require("./circle");

console.log(calculateArea(5));
console.log(calculateCircumference(5));

 statements are synchronous, which means CommonJS modules are loaded synchronously. Provided the application's single entry point, CommonJS automatically knows how to order the modules and dependencies and handle circular dependencies.

If you decide to use CommonJS modules for your client-side applications, then you need additional tooling, such as 

, to bundle and transpile the modules into a single file that can be understood and ran by a browser. Remember, CommonJS is not part of the official JavaScript specification.

Much like IIFEs, CommonJS was not designed for generating small bundle sizes. Bundle size was not factored into CommonJS's design since CommonJS is mostly used for developing server-side applications. For client-side applications, the code must be 

 first before running it. As a result, larger bundle sizes serve as performance bottlenecks that slow down an application. Plus, without tree-shaking, this makes CommonJS a non-optimal module system for client-side applications. 

 (AMD) asynchronously loads modules and their dependencies. Originating from the Dojo Toolkit, AMD is designed for client-side applications and doesn't require any additional tooling. In fact, all you need to run applications following the AMD module format is the 

 library, an in-browser module loader. That's it. Here's a simple example that runs a simple React application, structured with AMD, in the browser.

<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>React + AMD</title>
</head>
<body>
  <div id="root"></div>
  <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"></script>
  <script type="text/javascript" src="main.js"></script>
</body>
</html>

requirejs.config({
  paths: {
    "react": "https://unpkg.com/react@15.3.2/dist/react",
    "react-dom": "https://unpkg.com/react-dom@15.3.2/dist/react-dom"
  }
});

requirejs([ "react", "react-dom" ], (React, ReactDOM) => {
  ReactDOM.render(
    React.createElement("p", {}, "Greetings!"),
    document.getElementById("root")
  );
});

 methods registers the factory function (the anonymous function passed as the second argument to these methods). AMD executes this function only after all the dependencies have been loaded and executed. Each module references dependencies by name, not by their global variable. Each dependency name is mapped to the location of the dependency's source code. 

AMD allows multiple modules to be defined within a single file, and it supports older browsers. However, it is not as popular as more modern module formats, such as ECMAScript modules and Universal Module Definition.

For libraries that support both client-side and server-side environments, the 

 (UMD) offers a unified solution for making modules compatible with many different module formats, such as CommonJS and AMD. Regardless of whether an application consumes your library as a CommonJS, AMD or IIFE module, UMD conditionally checks for the module format being used at runtime and executes code specific to the detected module format. 

The UMD template code is an intimidating-looking IIFE, but it is not difficult to understand. Here's UMD in action from 

 function contains the actual library code.

 (ESM), the most recently introduced and recommended module format, is the standard and official way of handling modules in JavaScript. Module bundlers support ESM and optimize the code using techniques like tree-shaking (removes unused code from the final output), which are not supported by other module formats. Loading and parsing modules is asynchronous, but executing them is synchronous. This module format is commonly used in TypeScript applications.

Similar to CommonJS, ESM provides multiple ways for exporting code: default exports or named exports. A file can only have one default export (

 syntax), but it can have any number of named exports (

export function calculateArea() {
  return Math.PI * Math.pow(radius, 2);
};

export function calculateCircumference() {
  return 2 * Math.PI * radius;
};

Importing these named exports separately tells the module bundler which portions of the imported module should be included in the outputted code. Any named exports not imported are omitted. This decreases the size of the library, which is useful if your library relies on a few methods from a large utility library like 

Ask yourself the following questions while building your library:

Once you answer these questions, you can tell the module bundler to output the code in specific module formats for users to consume it within their own libraries/projects.

The newline Guide to Creating React Libraries from Scratch

where we teach you everything you need to know to succeed in creating your own library. 

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Tutorials on Javascript Library

Which Module Formats Should Your JavaScript Library Support?

Email Newsletter

Popular Topics

Masterclasses

Tutorials

Fullstack React with TypeScript