Node.js URL Module Guide

The URL module provides utilities for URL parsing and manipulation using the WHATWG URL Standard.

URL Class#

// Create URL object
const myURL = new URL('https://user:pass@example.com:8080/path/name?query=value#hash');

console.log(myURL.href);       // Full URL
console.log(myURL.protocol);   // 'https:'
console.log(myURL.username);   // 'user'
console.log(myURL.password);   // 'pass'
console.log(myURL.host);       // 'example.com:8080'
console.log(myURL.hostname);   // 'example.com'
console.log(myURL.port);       // '8080'
console.log(myURL.pathname);   // '/path/name'
console.log(myURL.search);     // '?query=value'
console.log(myURL.hash);       // '#hash'
console.log(myURL.origin);     // 'https://example.com:8080'

// Modify URL parts
myURL.pathname = '/new/path';
myURL.hash = 'section';
console.log(myURL.href);
// 'https://user:pass@example.com:8080/new/path?query=value#section'

Relative URLs#

// Resolve relative URL against base
const base = new URL('https://example.com/path/page.html');
const relative = new URL('../other/file.html', base);

console.log(relative.href);
// 'https://example.com/other/file.html'

// Various relative paths
new URL('/absolute', 'https://example.com/path/');
// 'https://example.com/absolute'

new URL('relative', 'https://example.com/path/');
// 'https://example.com/path/relative'

new URL('./same-level', 'https://example.com/path/');
// 'https://example.com/path/same-level'

new URL('../parent-level', 'https://example.com/path/sub/');
// 'https://example.com/path/parent-level'

// Protocol-relative
new URL('//cdn.example.com/file.js', 'https://example.com');
// 'https://cdn.example.com/file.js'

URLSearchParams#

// Parse query string
const url = new URL('https://example.com?name=John&age=30&hobby=coding&hobby=reading');
const params = url.searchParams;

// Get values
params.get('name');        // 'John'
params.get('age');         // '30'
params.get('hobby');       // 'coding' (first value)
params.getAll('hobby');    // ['coding', 'reading']
params.has('name');        // true

// Iterate
for (const [key, value] of params) {
  console.log(`${key}: ${value}`);
}

params.forEach((value, key) => {
  console.log(`${key}: ${value}`);
});

// Keys and values
[...params.keys()];    // ['name', 'age', 'hobby', 'hobby']
[...params.values()];  // ['John', '30', 'coding', 'reading']
[...params.entries()]; // [['name', 'John'], ...]

// Modify
params.set('name', 'Jane');     // Replace value
params.append('skill', 'js');   // Add new
params.delete('age');           // Remove

console.log(url.href);
// 'https://example.com/?name=Jane&hobby=coding&hobby=reading&skill=js'

Creating URLSearchParams#

// From string
const params1 = new URLSearchParams('name=John&age=30');

// From object
const params2 = new URLSearchParams({
  name: 'John',
  age: '30',
  active: 'true'
});

// From array of pairs
const params3 = new URLSearchParams([
  ['name', 'John'],
  ['hobby', 'coding'],
  ['hobby', 'reading']  // Duplicate keys allowed
]);

// From another URLSearchParams
const params4 = new URLSearchParams(params1);

// Convert to string
params2.toString();  // 'name=John&age=30&active=true'

// Sort alphabetically
params2.sort();
params2.toString();  // 'active=true&age=30&name=John'

URL Encoding#

// URLSearchParams handles encoding
const params = new URLSearchParams();
params.set('query', 'hello world');
params.set('special', 'a&b=c');

params.toString();
// 'query=hello+world&special=a%26b%3Dc'

// Manual encoding
encodeURIComponent('hello world');  // 'hello%20world'
encodeURI('https://example.com/path with spaces');
// 'https://example.com/path%20with%20spaces'

// Decoding
decodeURIComponent('hello%20world');  // 'hello world'
decodeURI('https://example.com/path%20with%20spaces');
// 'https://example.com/path with spaces'

Building URLs#

// Build URL programmatically
function buildUrl(base, path, params = {}) {
  const url = new URL(path, base);

  Object.entries(params).forEach(([key, value]) => {
    if (Array.isArray(value)) {
      value.forEach(v => url.searchParams.append(key, v));
    } else if (value !== undefined && value !== null) {
      url.searchParams.set(key, String(value));
    }
  });

  return url.href;
}

const apiUrl = buildUrl('https://api.example.com', '/users', {
  page: 1,
  limit: 10,
  sort: 'name',
  filter: ['active', 'verified']
});

// 'https://api.example.com/users?page=1&limit=10&sort=name&filter=active&filter=verified'

// URL builder class
class UrlBuilder {
  constructor(base) {
    this.url = new URL(base);
  }

  path(path) {
    this.url.pathname = path;
    return this;
  }

  query(key, value) {
    this.url.searchParams.set(key, value);
    return this;
  }

  queries(params) {
    Object.entries(params).forEach(([k, v]) => {
      this.url.searchParams.set(k, v);
    });
    return this;
  }

  hash(hash) {
    this.url.hash = hash;
    return this;
  }

  build() {
    return this.url.href;
  }
}

const url = new UrlBuilder('https://example.com')
  .path('/api/users')
  .queries({ page: '1', limit: '20' })
  .hash('results')
  .build();

Validating URLs#

// Check if string is valid URL
function isValidUrl(string) {
  try {
    new URL(string);
    return true;
  } catch {
    return false;
  }
}

isValidUrl('https://example.com');  // true
isValidUrl('not a url');            // false
isValidUrl('example.com');          // false (no protocol)

// Validate with constraints
function isValidHttpUrl(string) {
  try {
    const url = new URL(string);
    return url.protocol === 'http:' || url.protocol === 'https:';
  } catch {
    return false;
  }
}

// Extract domain
function getDomain(urlString) {
  try {
    const url = new URL(urlString);
    return url.hostname;
  } catch {
    return null;
  }
}

getDomain('https://www.example.com/path');  // 'www.example.com'

URL Comparison#

// URLs are normalized
const url1 = new URL('HTTPS://Example.COM/path/');
const url2 = new URL('https://example.com/path/');

url1.href === url2.href;  // true (both normalized)

// Compare specific parts
function isSameOrigin(url1, url2) {
  const a = new URL(url1);
  const b = new URL(url2);
  return a.origin === b.origin;
}

isSameOrigin(
  'https://example.com/path1',
  'https://example.com/path2'
);  // true

isSameOrigin(
  'https://example.com',
  'https://api.example.com'
);  // false (different subdomain)

// Check if URL matches pattern
function matchesPattern(url, pattern) {
  const urlObj = new URL(url);
  const patternObj = new URL(pattern);

  return (
    urlObj.hostname === patternObj.hostname &&
    urlObj.pathname.startsWith(patternObj.pathname)
  );
}

File URLs#

import { fileURLToPath, pathToFileURL } from 'url';
import { dirname } from 'path';

// Convert file URL to path
const filePath = fileURLToPath(import.meta.url);
// /Users/user/project/file.js

// Get directory name (ESM equivalent of __dirname)
const __dirname = dirname(fileURLToPath(import.meta.url));

// Convert path to file URL
const url = pathToFileURL('/path/to/file.js');
// file:///path/to/file.js

// Works with import()
const config = await import(pathToFileURL('./config.js'));

Legacy URL Module#

import { parse, format, resolve } from 'url';

// Legacy parse (deprecated but still works)
const parsed = parse('https://example.com/path?query=value', true);
console.log(parsed.query);  // { query: 'value' } as object

// Legacy format
const formatted = format({
  protocol: 'https',
  hostname: 'example.com',
  pathname: '/path',
  query: { key: 'value' }
});
// 'https://example.com/path?key=value'

// Legacy resolve
resolve('https://example.com/path/', '../other');
// 'https://example.com/other'

// Prefer WHATWG URL class for new code

Common Patterns#

// Extract pathname segments
function getPathSegments(urlString) {
  const url = new URL(urlString);
  return url.pathname.split('/').filter(Boolean);
}

getPathSegments('https://example.com/api/v1/users');
// ['api', 'v1', 'users']

// Add/update single query parameter
function setQueryParam(urlString, key, value) {
  const url = new URL(urlString);
  url.searchParams.set(key, value);
  return url.href;
}

// Remove query parameter
function removeQueryParam(urlString, key) {
  const url = new URL(urlString);
  url.searchParams.delete(key);
  return url.href;
}

// Get clean URL (no query, no hash)
function getCleanUrl(urlString) {
  const url = new URL(urlString);
  url.search = '';
  url.hash = '';
  return url.href;
}

// Parse hash parameters (for SPAs)
function parseHashParams(urlString) {
  const url = new URL(urlString);
  const hashParams = new URLSearchParams(url.hash.slice(1));
  return Object.fromEntries(hashParams);
}

parseHashParams('https://example.com#access_token=abc&expires_in=3600');
// { access_token: 'abc', expires_in: '3600' }

Best Practices#

URL Class:
✓ Use WHATWG URL class (new URL)
✓ Handle URL construction errors
✓ Use searchParams for query strings
✓ Normalize URLs for comparison

Security:
✓ Validate URLs before use
✓ Check protocol (http/https)
✓ Sanitize user-provided URLs
✓ Use URL encoding for parameters

Patterns:
✓ Create URL builders for complex URLs
✓ Use relative URLs when possible
✓ Extract common URL operations
✓ Handle edge cases

Avoid:
✗ String concatenation for URLs
✗ Manual query string building
✗ Forgetting to encode values
✗ Using deprecated url.parse

The Node.js URL module provides robust URL parsing and manipulation following the WHATWG URL Standard. Use the URL class for parsing and constructing URLs, URLSearchParams for query string handling, and fileURLToPath/pathToFileURL for file system integration. Always validate URLs and use proper encoding. The modern URL class should be preferred over the legacy url.parse function.