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.
const os = await import("node:os"); // exact types const mod = await import(computedPath); // Promise<any>
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 readFileSync(0)), 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 readFileSync(0)), it gets the next line from this box.
Syntax
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 aSyntaxError. Wrap awaited imports intry/catchwhen 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 turnimport()into a promise wrapped aroundrequire, so the loaded module is treated as CommonJS. Thenode16andnodenextsettings keep a realimport(). - 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
defaultset tomodule.exports; named properties exist only if Node can detect them. See ESM and CJS interop. - Top-level
awaitmakes anawait 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 typeandtypeof import("x")are type-only and never cause loading.- Do not build specifiers from untrusted input: it can load arbitrary files.
Related
- ES modules, import.meta, Importing JSON
- Lessons: Modules, Promises and async