Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท Modules and Declaration Files

import.meta in TypeScript

Reference for import.meta in TypeScript: url, dirname, filename and resolve in Node, which module settings allow it, and how to add your own typed properties.

import.meta is an object that holds information about the current ES module. The language itself defines only the object; the host fills it in. In Node.js it provides url, dirname, filename and resolve(). Bundlers and runtimes add their own fields, such as env in Vite.

The object is only valid inside ES modules, which is why it replaces __dirname and __filename: those two variables exist in CommonJS only. TypeScript allows import.meta when the output is an ES module (module set to es2020 or later, node16, nodenext or preserve) and reports an error for CommonJS output. Its type is the global ImportMeta interface, so you extend it with declaration merging.

TypeScript
const here = import.meta.dirname;
const self = new URL(import.meta.url);

Try it

TypeScript What Node puts in import.meta

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 Extending ImportMeta

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
interface ImportMeta {
  url: string;
  dirname: string;     // Node 20.11+, @types/node
  filename: string;    // Node 20.11+, @types/node
  resolve(specifier: string): string;
}
Property Description
import.meta.url The absolute file: URL of the current module as a string. Needed with new URL("./data.json", import.meta.url) to build paths that do not depend on the working directory.
import.meta.dirname The directory of the module as a file path. Same as CommonJS __dirname. Only for file: modules.
import.meta.filename The module's file path. Same as __filename.
import.meta.resolve(specifier) Resolves a specifier the way import would and returns the URL string, without loading it.

Errors and edge cases:

  • In a file that compiles to CommonJS, import.meta is error TS1343: it is only allowed when module is es2020, es2022, esnext, system, node16, node18, node20, nodenext or preserve.
  • Properties that Node does not set read as undefined, but the standard ImportMeta interface hides them, so declare optional types for host-specific fields as in the second example.
  • import.meta.dirname and filename are not defined for non-file: modules such as data: URLs.
  • import.meta is not available outside modules. A plain script has no such object.

Usage notes

  • Prefer import.meta.dirname over rebuilding it from fileURLToPath(import.meta.url); both give the same result in Node 20.11 and later.
  • Relative file access with fs resolves against the process working directory, not against the module. Anchor it with join(import.meta.dirname, "file.txt").
  • import.meta.resolve returns a string and reflects the module's own resolution rules, including package exports. See Module resolution.
  • Declare extra fields in a .d.ts file (for example vite/client does this) so every file sees them.
  • Do not rely on the exact set of keys: runtimes may add more. The second example sorts them and shows what Node 24 provides: dirname, filename, main, resolve and url (main is true only in the entry module).
  • Deno and Bun support the same core fields, and browsers provide url only.