JavaScript Reference ยท Classes and Modules
ES modules
Concept page on JavaScript ES modules: how import and export work, live bindings, strict mode, one shared instance, dynamic import(), top-level await and loading.
An ES module is a JavaScript file that declares what it shares with export and pulls in what it needs with import. Modules have their own scope, so nothing leaks into the global object, and the language, not a library, defines how they load. Browsers, Node.js and bundlers all understand the same syntax.
This page explains how modules behave. For the exact syntax of each form, see import and export.
// math.js export const PI = 3.14159; export function area(r) { return PI * r * r; } export default class Circle {} // app.js import Circle, { PI, area } from "./math.js"; import * as math from "./math.js";
Using a module in a page
Mark the script as a module. The file is then fetched with CORS and runs after the document is parsed, like defer.
<script type="module" src="/js/app.js"></script> <script type="module"> import { area } from "/js/math.js"; console.log(area(2)); </script>
In Node.js, a file is a module when it ends in .mjs, or in .js with "type": "module" in the nearest package.json. Browser specifiers must be full paths or URLs ("./math.js", not "math"), unless an import map maps bare names to URLs.
Module code is different
Press Run (or Ctrl + Enter) to see the console output here.
No output.
The rules that set modules apart:
- Always strict mode. No
"use strict"needed. - Own top-level scope. Variables, functions and classes are private to the module unless exported.
thisat the top level isundefined.- Top-level
awaitis allowed. A module that awaits delays the modules that import it. import.metacarries information about the module, such asimport.meta.url. See import.meta.- Imports are hoisted. They are resolved and loaded before any code in the module runs, wherever the
importline appears.
One instance, live bindings
A module is evaluated once, no matter how many files import it. Every importer shares the same module instance, which is why a module works as a singleton.
Imported names are live, read-only views of the exporter's variables, not copies. If the exporting module changes the value, importers see the change; importers cannot assign to them.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Static and dynamic import
- A static
importdeclaration must be at the top level, takes a string literal, and is analyzed before the code runs. That lets tools find unused exports (tree shaking) and detect missing names early. - A dynamic
import(specifier)is an expression. It can run anywhere, accept a computed string, and returns a promise for the module's namespace object. Use it for code splitting and loading rarely used features on demand. - Default vs named exports. A module has at most one default export; named exports can be many. Namespace imports (
import * as m) collect them in one object. - Re-exporting:
export { x } from "./a.js"andexport * from "./a.js"build barrel files.export *does not re-export the default. - Circular imports are allowed because bindings are live, but reading a binding before its module has run throws a
ReferenceErrorforlet,constandclass. Avoid cycles that run code at load time.
Usage notes
- Remember CORS and the file protocol. Browsers refuse module scripts from
file://pages and from other origins without CORS headers. Serve the files over HTTP. - Failures. A failed import (404, syntax error, missing named export) aborts the whole module graph. A missing name is a
SyntaxErrorbefore anything executes. - Do not mix with old scripts blindly. Classic scripts cannot use
import; use<script type="module">, or dynamicimport()which works in classic scripts too. - Extensions and paths are required in browsers and native Node.js ESM.
- Interop. CommonJS (
require) and ESM differ; newer Node.js versions canrequire()synchronous ES modules, and ESM can import CommonJS.
Browser support
ES modules, dynamic import() and top-level await are supported in all current browsers. Import maps and import.meta features beyond url are newer; check a compatibility table.