Skip to content
Tutorials Center
My learning

Topics

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.

NODE
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

Node.js Named, default and namespace

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.

Node.js Live bindings and JSON attributes

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:

NODE
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:

NODE
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. import declarations are only allowed at the top level of a module, are resolved before any code runs, and cannot take a computed string. For that, use import().
  • 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 .js or index.js: write ./util.js or ./dir/index.js in full.
  • Default export versus named. Prefer named exports in libraries; they are easier to tree-shake and autocomplete. export default makes a single name that every importer is free to rename.
  • Importing CommonJS. module.exports becomes the default import, and Node tries to detect named exports with a static scan, so import { readFile } from './cjs.cjs' sometimes works and sometimes does not. The default import always does.
  • Strict mode is always on, this at the top level is undefined, and require, module, exports, __filename and __dirname do not exist (use import.meta.filename and import.meta.dirname).
  • Circular imports work, but a module may see a name that is not initialized yet (an access error for let, const and classes).
  • Top-level await is allowed; see Top-level await.
  • Import attributes use the with keyword. The older assert keyword was removed.