liveBook · Manning

ECMAScript module

As explained in Secrets of the JavaScript Ninja, Third Edition

A JavaScript module whose dependencies and shared bindings are declared using standardized import and export syntax.

A growing JavaScript application needs a better way to share code than loading scripts in the right order and hoping their global names do not collide. An ECMAScript module (ESM) is a JavaScript file that declares what it uses with imports and what it shares with exports. Those declarations make dependencies explicit while letting code remain in smaller, relatively self-contained files. section 13.1 section 1.1

ESM is the standardized alternative to older module approaches such as CommonJS. It supports named and default exports, including both in one module. An exported value is a live binding: the exporting module can reassign it, but an importer can only read it. Static imports are resolved when the module is parsed; asynchronous import() runs at runtime when deferred loading is useful. section 13.0 section 13.4

Static and deferred imports

A package consumer can write import { getRandomTurtle } from "entry-point-example/ninjas/turtles". Another exported function can instead call await import("./ninjas/turtles.js") when it runs. The first dependency appears in a static import; the second is requested at runtime. section 13.1.2 section 13.4

An import string does not, by itself, say where a file lives. The ESM specification leaves that resolution to the runtime. In Node.js, a bare package name leads to a search in node_modules; the package’s package.json can then map public entry points through its exports field. In a browser, an import map can map a bare name to a URL. section 13.1.2

Listing 13.9 Defining entry points for a package
{
  "name": "entry-point-example",
  "private": true,
  "type": "module", #A
  "exports": { #B
    ".": "./lib/index.js", #B
    "./ninjas/*": "./lib/ninjas/*.js" #B
  } #B
}

The package manifest marks .js files as ESM with "type": "module" and maps both the package root and a subpath through "exports". section 13.1.2

Listing 13.13 Defining an import map in HTML
<html>
  <head>
    <title>ESM Ninja</title>
    <script type="importmap"> #A
      { #A
        "imports": { #A
          "esm-ninja": "/assets/esm-ninja.js" #A
        } #A
      } #A
    </script> #A
    <script #B
      type="module" #B
      src="/assets/app.js" #B
    ></script> #B
  </head>
  <body>
    <p>Loading...</p>
  </body>
</html>

The HTML example maps a bare import name to a browser URL, then loads the application with a module script. section 13.1.2

Watch the runtime and package boundary. Node.js supports both ESM and CommonJS: .mjs identifies an ESM file, while a package’s "type": "module" makes its .js files ESM. CommonJS generally imports into ESM readily, but importing ESM from CommonJS is trickier; top-level await in ESM can also cause an error when that module is loaded from CommonJS. For web delivery, a bundler can combine modules into chunks and optimize the result. section 3.1.2 section 13.4 section 13.1.2

How Secrets of the JavaScript Ninja, Third Edition covers it

How deep it goes
Explains export forms, live bindings and import timing, then traces specifier resolution to runtime-specific configuration.
Examples
Uses a Node.js calculator, a package with root and subpath exports, and an HTML import map.
What it assumes
Builds on JavaScript files and browser scripts while introducing module syntax and Node.js package configuration.
What you can do after
Operate/configure ESM in Node.js packages and browser pages, choosing static or runtime imports and recognizing CommonJS compatibility pitfalls.
How it connects
Connects ESM to CommonJS, dependency graphs, Node.js packages, browser import maps and bundlers.

Also explained in

Compare how 2 books explain ECMAScript module →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Secrets of the JavaScript Ninja, Third Edition. The section links point to the parts of the book it draws on.