Alternatives to __dirname in Node.js ES Modules

The __dirname Problem in ES Modules

If you've migrated a Node.js project to ES Modules (ESM), you've likely encountered the frustrating error: "__dirname is not defined". This isn't a bug--it's a fundamental difference between how CommonJS and ES Modules handle module-level variables.

Why CommonJS Has __dirname but ESM Doesn't

In CommonJS, __dirname and __filename are implicit globals provided by Node.js's module wrapper function. When you write require('./module.js'), Node.js wraps your code in a function that exposes these variables along with module, exports, require, and __filename.

ES Modules follow a different specification--the ECMAScript standard--which doesn't define __dirname or __filename. Instead, ESM provides import.meta, an object that contains metadata about the current module. While import.meta.url gives you the file's URL, directory and filename information requires additional processing.

The Migration Challenge

For developers transitioning legacy CommonJS codebases to ES Modules, path-related variables are among the most common friction points. Code that resolves configuration file paths, loads assets relative to the module location, or constructs dynamic file paths breaks immediately in ESM unless refactored.

Modern frameworks like Next.js default to ES Modules, making this knowledge essential for contemporary web development. Understanding path resolution patterns becomes crucial when building scalable applications that leverage modern JavaScript capabilities.

Modern Solution: import.meta.dirname and import.meta.filename

Native ES Module Support (Node.js 20.11+)

Starting with Node.js 20.11, the runtime added experimental support for import.meta.dirname and import.meta.filename, matching the familiar CommonJS globals within ES module scope.

// Available in Node.js 20.11+
console.log(import.meta.dirname); // /path/to/project/src/utils
console.log(import.meta.filename); // /path/to/project/src/utils/helper.js

These properties are stabilized in newer Node.js versions and represent the cleanest solution for projects targeting modern runtime environments. The feature is enabled by default when running ESM code--no configuration flags required.

Requirements and Compatibility

For production deployments, ensure your Node.js version supports these properties:

• Node.js 20.11+ (experimental initially)
• Node.js 22+ (fully stabilized)

Check runtime support programmatically:

// Feature detection
if (typeof import.meta.dirname !== 'undefined') {
 // Use import.meta.dirname
} else {
 // Fall back to URL-based workaround
}

This approach future-proofs your code while maintaining backward compatibility across different deployment environments.

Legacy Workaround: The URL-Based Approach

Using import.meta.url with fileURLToPath

For projects supporting older Node.js versions, the canonical workaround involves three steps: extracting the module's URL, converting it to a file path, and extracting the directory.

import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

This pattern works universally across all Node.js versions that support ES Modules and produces identical values to the CommonJS globals.

How the URL-Based Approach Works

The import.meta.url property returns a file:// URL representing the current module's location:

file:///Users/developer/project/src/utils/helper.js

The fileURLToPath function converts this URL to a native filesystem path:

/Users/developer/project/src/utils/helper.js

Finally, path.dirname extracts the directory portion:

/Users/developer/project/src/utils

Handling Path Separators Across Platforms

One critical consideration when working with the URL-based approach is cross-platform compatibility. Windows uses backslash (\) path separators, while Unix systems use forward slash (/). Both fileURLToPath and path.dirname handle these conversions automatically, ensuring your code works correctly regardless of the deployment platform.

However, be cautious when constructing paths manually or comparing paths across systems. Always use path.join(), path.resolve(), or the URL constructor for path construction rather than string concatenation. This pattern integrates well with Node.js streams and configuration management for building robust file processing pipelines.

Alternative Patterns and Utilities

Creating a Drop-in Replacement

For easier migration of existing codebases, create a utility module that provides consistent behavior:

// esm-utils.js
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const __filename = typeof fileURLToPath !== 'undefined'
 ? fileURLToPath(import.meta.url)
 : null;
const __dirname = typeof __filename !== 'null'
 ? dirname(__filename)
 : null;

export { __filename, __dirname };

Import this utility in your modules:

import { __dirname, __filename } from './esm-utils.js';

Using URL Objects Directly

For certain use cases, working with URL objects directly avoids path conversion entirely:

// Resolve relative to module location
const configUrl = new URL('../config/settings.json', import.meta.url);
const assetUrl = new URL('./assets/logo.png', import.meta.url);

// Convert to path when needed
import { pathToFileURL } from 'node:url';
const filePath = pathToFileURL(configUrl).pathname;

The URL constructor handles path joining and normalization automatically, making it resistant to path separator issues and trailing slash inconsistencies. This approach pairs well with Node.js configuration file patterns for managing application settings across environments.

Importing JSON and Other Assets

ES Modules don't natively support importing JSON or other asset files without configuration. The URL-based approach provides a clean solution:

import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { readFileSync } from 'node:fs';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// Read JSON config file
const configPath = join(__dirname, './config.json');
const configData = JSON.parse(readFileSync(configPath, 'utf-8'));

Best Practices and Performance Considerations

Path Resolution Performance

Path resolution using fileURLToPath and path.dirname adds minimal overhead--typically microseconds. For most applications, this is negligible. However, in hot paths or frequently imported utility modules, consider caching the results:

import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

// Compute once, reuse
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// Export for reuse
export { __dirname };

Security Considerations

When working with user-provided paths, sanitize inputs before passing them to path resolution functions:

import { join } from 'node:path';

function safeResolve(baseDir, userPath) {
 // Prevent directory traversal attacks
 const sanitized = userPath.replace(/(\.\.[\/\\])+/g, '');
 return join(baseDir, sanitized);
}

Always validate that resolved paths remain within expected directories, especially when serving user-generated content or processing external configurations.

TypeScript Compatibility

When using TypeScript, import.meta.dirname may require type augmentation or explicit casting. Many projects opt for the URL-based approach for better type compatibility and fewer configuration requirements. Building secure and performant Node.js applications requires attention to these best practices for modern web development.

Integration with Modern Frameworks

Next.js and Vite

Modern frameworks like Next.js and Vite handle module resolution automatically in most cases. Their build processes transform imports and manage path resolution, reducing the need for manual __dirname handling.

In Next.js API routes and server-side code, prefer using process.cwd() for project-root-relative paths:

import { join } from 'node:path';
import { readFileSync } from 'node:fs';

const projectRoot = process.cwd();
const configPath = join(projectRoot, 'config/settings.json');

For files that must reference their own location (such as utilities loading adjacent resources), the URL-based approach remains reliable.

Serverless and Edge Environments

When deploying to serverless platforms (AWS Lambda, Vercel, Netlify Functions), the URL-based approach works consistently:

import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// This pattern works in serverless environments
const templatePath = join(__dirname, './templates/email.html');

Be aware that some edge runtimes have limited file system access. In these environments, consider bundling templates as strings or using remote configuration services. For applications requiring AI-powered automation, proper path handling ensures reliable template and configuration loading across all environments.

Sources

1. LogRocket: Alternatives to __dirname in Node.js with ES Modules
2. Sonar: __dirname is back in Node.js with ES modules
3. Better Stack: CommonJS vs ES Modules