Node.js Reference ยท Module Systems
ES module syntax in Node.js: import and export
Reference for ES module syntax in Node.js: named and default exports, namespace imports, re-exports, live bindings, import attributes for JSON and import.meta.
import and export are the standard JavaScript syntax for sharing code between files. A file that uses them is an ES module (ESM). Node.js treats a file as an ES module when its name ends in .mjs, when the nearest package.json has "type": "module", or when the code is run in a way that forces it. See package.json type for the full rules.
This page is a compact reference for the syntax and for the Node.js-specific details: file extensions in specifiers, the node: prefix, JSON import attributes and import.meta. Every example below writes small module files into a temporary folder and loads them with import(), so you can see both sides of a module in one editor.
import { readFile } from 'node:fs/promises'; // named import import path from 'node:path'; // default import import * as os from 'node:os'; // namespace import export const answer = 42; export default function greet() {}
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
Exports:
export const a = 1; // named export of a declaration export { a as b, c }; // list of names, with renaming export default expression; // one default export per module export { default } from './x.mjs'; // re-export the default export { a, b as c } from './x.mjs'; export * from './x.mjs'; // everything except default export * as ns from './x.mjs'; // namespace object as one name
Imports:
import def from './x.mjs'; import { a, b as c } from './x.mjs'; import def, { a } from './x.mjs'; import * as ns from './x.mjs'; import './x.mjs'; // run it for its side effects only import data from './d.json' with { type: 'json' };
| Part | Description |
|---|---|
| Specifier | The string after from. Relative (./a.mjs, ../b.mjs), absolute (file:///...), a bare package name (express), a subpath of a package (lodash/fp), a #-import (package.json imports), or a built-in (node:fs). |
with { type: 'json' } |
Import attributes. Required in Node.js to import JSON; other types are not supported. |
import.meta |
Per-module object with url, filename, dirname and resolve(). |
Errors: a missing file gives ERR_MODULE_NOT_FOUND; a name that the target does not export is a SyntaxError at link time ("does not provide an export named ..."); assigning to an imported name throws a TypeError.
Usage notes
- Static and hoisted.
importdeclarations are only allowed at the top level of a module, are resolved before any code runs, and cannot take a computed string. For that, useimport(). - Live bindings. An imported name is a read-only view of the exporting module's variable. If the exporter changes it, importers see the new value.
- Extensions are mandatory. Unlike CommonJS, ESM does not guess
.jsorindex.js: write./util.jsor./dir/index.jsin full. - Default export versus named. Prefer named exports in libraries; they are easier to tree-shake and autocomplete.
export defaultmakes a single name that every importer is free to rename. - Importing CommonJS.
module.exportsbecomes the default import, and Node tries to detect named exports with a static scan, soimport { readFile } from './cjs.cjs'sometimes works and sometimes does not. The default import always does. - Strict mode is always on,
thisat the top level isundefined, andrequire,module,exports,__filenameand__dirnamedo not exist (useimport.meta.filenameandimport.meta.dirname). - Circular imports work, but a module may see a name that is not initialized yet (an access error for
let,constand classes). - Top-level
awaitis allowed; see Top-level await. - Import attributes use the
withkeyword. The olderassertkeyword was removed.