Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Modules and Declaration Files

Dynamic import() in TypeScript

How dynamic import() is typed in TypeScript: literal specifiers give exact module types, computed ones give any, plus import attributes, errors and lazy loading.

import(specifier) loads a module on demand and returns a promise for its namespace object: every named export as a property, and the default export under default. It works in ES modules and CommonJS files alike, and it can appear anywhere an expression is allowed, such as inside an if, a function or an event handler. Use it for code splitting, optional features and for loading a module whose name is only known at run time.

TypeScript types the result by looking at the specifier. A string literal that resolves to a file gives you the exact type of that module. A computed specifier cannot be resolved, so the result is Promise<any> and you describe the shape yourself.

TypeScript
const os = await import("node:os");        // exact types
const mod = await import(computedPath);    // Promise<any>

Try it

TypeScript Typed dynamic imports

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 readFileSync(0)), it gets the next line from this box.

TypeScript Computed specifiers and failures

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 readFileSync(0)), it gets the next line from this box.

Syntax

TypeScript
import(specifier: string): Promise<ModuleNamespace>
import(specifier: string, options: { with: { type: "json" } }): Promise<ModuleNamespace>
Name Description
specifier Relative path, bare package name, node: built-in or URL. Relative paths resolve against the importing file; in Node file: URLs are the safe way to build paths.
options.with Import attributes. JSON modules need { type: "json" } in Node.

Returns a promise that resolves to the namespace object, which also holds a default property for the default export.

Errors and edge cases:

  • A missing file rejects with ERR_MODULE_NOT_FOUND; a syntax error in the target rejects with a SyntaxError. Wrap awaited imports in try/catch when loading is optional.
  • A computed specifier is typed any. Assert it to an interface you wrote, and remember the assertion is not checked.
  • Under module: "commonjs" the compiler may turn import() into a promise wrapped around require, so the loaded module is treated as CommonJS. The node16 and nodenext settings keep a real import().
  • Types declared in the target are erased; only values exist in the namespace object.

Usage notes

  • Each specifier is evaluated once. Later calls return the same namespace object, so module-level state is shared.
  • A CommonJS target appears with default set to module.exports; named properties exist only if Node can detect them. See ESM and CJS interop.
  • Top-level await makes an await import() easy to use at the start of a module, but it blocks the importers of that module until it finishes.
  • Bundlers can split code at import("./literal.js") because the path is static. A computed path usually defeats this unless the bundler supports patterns.
  • import type and typeof import("x") are type-only and never cause loading.
  • Do not build specifiers from untrusted input: it can load arbitrary files.