Node.js Reference ยท Module Systems
Dynamic import() in Node.js
Reference for dynamic import() in Node.js: load ES modules, CommonJS files, JSON and built-ins at runtime, handle errors, and understand caching and cache busting.
import(specifier) looks like a function call but is special syntax: it loads a module at runtime and returns a promise for the module namespace object. Unlike a static import, it can be used anywhere (inside functions, if blocks, event handlers), the specifier can be computed, and it works in both ES modules and CommonJS files.
Use it to load code only when it is needed (a plugin chosen by a setting, a heavy dependency used by one command), to load an ES module from CommonJS code, and to react to a missing optional dependency without crashing at start-up.
const { join } = await import('node:path'); const mod = await import('./plugin.mjs');
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
import(specifier: string, options?: { with?: { type: 'json' } }): Promise<Namespace>
| Name | Description |
|---|---|
specifier |
Same rules as a static import: a relative path with extension (resolved against the file that contains the call), a file: URL, a bare package name, a # import or a node: built-in. |
options.with |
Import attributes. { type: 'json' } is needed for .json files. |
Returns: a promise that resolves to the module namespace object. A module with a default export has it under .default. For a CommonJS target, .default is module.exports, and detected named exports are copied onto the namespace.
Errors: the promise rejects with ERR_MODULE_NOT_FOUND for a missing file or package, ERR_PACKAGE_PATH_NOT_EXPORTED for a blocked subpath, ERR_UNSUPPORTED_DIR_IMPORT for a directory, or with whatever the module itself throws while it runs (including SyntaxError for bad code).
Usage notes
- Relative to the importing file. A relative specifier is resolved from the file that contains
import(), not fromprocess.cwd(). From code in a string or in the REPL it is relative to the current directory. - Absolute paths on Windows such as
C:\x\a.mjsare read as a URL with the schemec:and fail. Convert withpathToFileURL()first, as the examples do. - Modules are cached by resolved URL. A second call returns the same namespace and does not run the module again. A query string (
?v=2) makes a new URL and so a fresh evaluation, but the old copy stays in memory, so do not use it in a loop; there is no supported way to unload an ES module. - CommonJS can use it too. It is the way to load an ES module from CommonJS code when
require(esm)cannot be used, for example when the target uses top-levelawait. - It is asynchronous, even for built-ins and already loaded files. Always
awaitit or use.then(). - Optional dependencies: wrap the call in
try/catchand checkerr.code === 'ERR_MODULE_NOT_FOUND', but compare the missing name too, so a missing import inside the module is not mistaken for a missing module. - Bundlers can only follow
import()calls whose specifier is a plain string; computed paths make the bundle larger or fail. - Security. Never pass user input as the specifier: it can load any file or URL scheme that Node supports, and the module's code runs with full privileges.