A Node.js ESM-friendly path utility for resolving file and directory paths.
- Unified API for ESM: pass either
import.metaor a string (like__dirname) - Works seamlessly in Node.js and modern ESM environments
- TypeScript type definitions included
- Simple, runtime dependency-free, and well-tested
pathUrl,resolvePath, andrelativePathhelpers based onimport.metafileUrlToPathfor converting file URLs back to filesystem paths
- Node.js 26 or newer
- Native ESM support
npm install @eliware/pathimport path, { fileUrlToPath, pathUrl, relativePath, resolvePath } from '@eliware/path';
// for ESM, we need to pass import.meta
const envFile = path(import.meta, ".env");
console.log(envFile);
// Get a file URL href for dynamic import
const envFileUrl = pathUrl(import.meta, ".env");
console.log(envFileUrl);
// import(envFileUrl).then(mod => ...);// ESM
import { pathUrl } from '@eliware/path';
const mod = await import(pathUrl(import.meta, './my-module.mjs'));Returns the filesystem path represented by import.meta. When passed a string
(for example, __dirname), returns that directory string unchanged. The
string form is always treated as a directory, not a filename. Throws if the
base is missing or does not contain a usable module URL.
Returns the directory path represented by import.meta or the supplied string.
The result is absolute when the input is absolute. Throws if the base is
missing or does not contain a usable module URL.
When dirnameFn is provided, it is used for ImportMeta inputs. Directory
string inputs are already directories, so the injected function is not called.
Joins the current dirname (from import.meta or a string) with provided
segments. The result follows the host platform’s native path behavior.
Returns a file URL href string for the resolved path, suitable for use with dynamic import() on all platforms.
Resolves path segments from the current directory and returns an absolute filesystem path.
Resolves the target from the current directory and returns its normalized path relative to that directory.
Converts a file URL string or URL object to a filesystem path.
Pass import.meta or a directory string to the helpers. Missing or invalid bases throw an error. Paths use the host platform’s native separators; pathUrl() returns a file URL suitable for dynamic imports.
No configuration is required. Each helper accepts an ImportMeta value or a
directory string; getCurrentDirname() also accepts an optional injected
dirname function for custom path behavior and testing.
The package has no runtime dependencies and performs no initialization at
import time. Development commands use the shared @eliware/test tool.
These helpers do not access the filesystem or perform network I/O. They only
convert and compose paths. Native path semantics allow absolute segments and
.. segments to escape the supplied base; validate user-controlled input and
enforce application-specific permissions before reading or writing files.
npm test
npm run lint
npm run typecheck
npm audit --omit=dev --audit-level=moderate
npm run packType definitions are included:
export function getCurrentFilename(metaOrDir: ImportMeta | string): string;
export function getCurrentDirname(metaOrDir: ImportMeta | string, dirnameFn?: (path: string) => string): string;
export const path: (metaOrDir: ImportMeta | string, ...segments: string[]) => string;
export function pathUrl(metaOrDir: ImportMeta | string, ...segments: string[]): string;
export function resolvePath(metaOrDir: ImportMeta | string, ...segments: string[]): string;
export function relativePath(metaOrDir: ImportMeta | string, ...segments: string[]): string;
export function fileUrlToPath(fileUrl: string | URL): string;
export default path;For help, questions, or to chat with the author and community, visit:
