In a Node ES module (a `.mjs` file, or a `.js` file in a package with `"type": "module"`), why is `__dirname` not defined, and how do you get the current file's directory instead?

## Where the CommonJS globals actually come from They are not globals at all. Before running a CommonJS file, Node wraps its source, conceptually, like this: ```js (function (exports, require, module, __filename, __dirname) { // your file's code }); ``` Every CJS file therefore runs inside a function whose parameters supply the module machinery. That single fact explains a lot of otherwise puzzling behaviour: `__dirname` differs per file rather than being process-wide, top-level `this` in CJS is `module.exports`, and top-level `var` does not leak to the global object. ECMAScript modules are a language feature with their own semantics, and Node loads them through the ESM loader, not the wrapper. No wrapper means no parameters: ```js console.log(__dirname); // ReferenceError: __dirname is not defined in ES module scope require('fs'); // ReferenceError: require is not defined in ES module scope ``` Those are exactly the messages Node prints, and they are pointing at the wrapper's absence, not at a missing feature. ## What ESM gives you instead `import.meta` is a syntactic form the language reserves for host-provided metadata about the current module. It is valid **only inside a module** — in a CommonJS file or a classic script it is a `SyntaxError`, not a runtime error, so a stray `import.meta` fails at parse time. Every host that implements ESM is expected to populate `import.meta.url` with the module's own URL: ```js console.log(import.meta.url); // Node: file:///Users/me/app/src/config.js // Browser: https://example.com/src/config.js ``` That difference is the whole point of the design. A URL is meaningful in both hosts; a filesystem path is not. ## Getting a path out of it A `file:` URL is not a path — it is percent-encoded, uses forward slashes even on Windows, and carries the `file://` scheme. Do not slice the string yourself. Node ships the conversion: ```js import { fileURLToPath } from 'node:url'; import path from 'node:path'; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); ``` Since Node 20.11.0 and 21.2.0 the same values are available directly: ```js console.log(import.meta.dirname, import.meta.filename); ``` On older versions those are `undefined`, so a library supporting a wide Node range still uses the `fileURLToPath` form. ## Often you do not need a path at all When the goal is "find a file next to this module", the URL constructor resolves it directly, and the result can be handed to APIs that accept file URLs: ```js const schemaUrl = new URL('./schema.json', import.meta.url); const text = await readFile(schemaUrl, 'utf8'); // node:fs/promises accepts a file URL ``` This is more robust than joining strings, because relative resolution against a URL handles `..`, encoding and separators correctly. ## Two related gaps and their fixes **`require` in ESM.** If you must load a CommonJS-only package synchronously, build a require function bound to your module's location: ```js import { createRequire } from 'node:module'; const require = createRequire(import.meta.url); ``` **Which entry file am I?** The CJS idiom `require.main === module` guarding "run only when executed directly" has no wrapper to lean on in ESM. The portable check compares the module's own URL with the process's entry argument: ```js import { fileURLToPath } from 'node:url'; if (process.argv[1] === fileURLToPath(import.meta.url)) { main(); } ``` ## The trap people hit anyway `process.cwd()` is not a substitute for `__dirname`. It is the directory the process was launched from, which changes depending on where the user typed the command; `__dirname`/`import.meta.dirname` is where the *file* lives. Reading a bundled asset relative to `cwd()` works on your machine and breaks the moment the tool is invoked from another folder. If the asset ships with the code, resolve it against the module URL. ## The short answer to give "`__dirname` is a CommonJS wrapper parameter, and ESM has no wrapper. The module-relative anchor in ESM is `import.meta.url`, a URL rather than a path, because that form also works in a browser. Convert with `fileURLToPath`, or read `import.meta.dirname` on Node 20.11+, and prefer `new URL('./file', import.meta.url)` when you are just locating a neighbouring asset."