path and url

node:path builds filesystem paths; node:url parses and resolves HTTP and file:// URLs - conflating them causes broken imports, bad redirects, and SSRF bugs.

Recipe

import path from 'node:path';
import { fileURLToPath } from 'node:url';
 
const dir = path.dirname(fileURLToPath(import.meta.url));
const config = path.join(dir, 'config.json');

import { URL } from 'node:url';
 
const u = new URL('https://api.example.com/v1/users?page=2');
u.searchParams.set('limit', '50');

When to reach for this:

• Resolving config files next to compiled dist/ output
• Building outbound API URLs with query params
• Validating redirect targets against allowlists (SSRF prevention)
• Converting import.meta.url to absolute filesystem path

Working Example

import path from 'node:path';
import { fileURLToPath, URL } from 'node:url';
 
// ESM __dirname equivalent
const root = path.dirname(fileURLToPath(import.meta.url));
const dataFile = path.resolve(root, '..', 'data', 'users.json');
 
// API URL with safe query building
function usersEndpoint(base: string, page: number): string {
  const url = new URL('/v1/users', base);
  url.searchParams.set('page', String(page));
  return url.href;
}
 
// SSRF guard - only allow https to known host
function assertAllowedTarget(href: string, allowedHosts: Set<string>): URL {
  const parsed = new URL(href);
  if (parsed.protocol !== 'https:') throw new Error('https required');
  if (!allowedHosts.has(parsed.hostname)) throw new Error('host not allowed');
  return parsed;
}

What this demonstrates:

• path.resolve and join prevent manual slash bugs
• URL constructor resolves relative paths against base URL
• searchParams encodes query strings correctly
• SSRF checks inspect protocol and hostname before fetch

Deep Dive

How It Works

• path is platform-aware (win32 vs posix internals) - path.join picks separators.
• URL follows WHATWG spec - same as browser URL.
• fileURLToPath / pathToFileURL bridge file URLs and filesystem paths.
• import.meta.resolve (experimental/stable per version) resolves specifiers like import.

path vs URL

TypeScript Notes

import path from 'node:path';
 
export function safeJoin(base: string, userSegment: string): string {
  const resolved = path.resolve(base, userSegment);
  if (!resolved.startsWith(path.resolve(base))) {
    throw new Error('path traversal');
  }
  return resolved;
}

Gotchas

• Using path for HTTP URLs - loses query/fragment semantics. Fix: URL for HTTP, path for disk.
• Path traversal in path.join(base, userInput) - ../etc/passwd. Fix: resolve and verify prefix under base.
• Assuming url.pathname is filesystem path on Windows - leading slash POSIX-like. Fix: fileURLToPath for file: URLs only.
• Double slashes in manual string concat - broken redirects. Fix: new URL(relative, base).
• IPv6 URLs without brackets - parse failures. Fix: new URL handles bracketed host http://[::1]:8080.

Alternatives

FAQs

Related

• fs and fs/promises - open resolved paths
• ES Modules import - import.meta.url
• SSRF Guards - URL validation
• Built-in APIs Basics - overview

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.