Node.js URL Module Guide

The URL module provides utilities for URL parsing and manipulation. Here's how to use it.

URL Constructor#

// Create URL from string
const url = new URL('https://example.com:8080/path/page?name=value#section');

console.log(url.href);      // Full URL string
console.log(url.protocol);  // 'https:'
console.log(url.host);      // 'example.com:8080'
console.log(url.hostname);  // 'example.com'
console.log(url.port);      // '8080'
console.log(url.pathname);  // '/path/page'
console.log(url.search);    // '?name=value'
console.log(url.hash);      // '#section'
console.log(url.origin);    // 'https://example.com:8080'

// With base URL
const relative = new URL('/api/users', 'https://example.com');
console.log(relative.href); // 'https://example.com/api/users'

// Resolve relative paths
const resolved = new URL('../images/photo.jpg', 'https://example.com/pages/about/');
console.log(resolved.href); // 'https://example.com/pages/images/photo.jpg'

Modifying URLs#

const url = new URL('https://example.com/path');

// Modify properties
url.pathname = '/new-path';
url.port = '3000';
url.hash = '#footer';

console.log(url.href);
// 'https://example.com:3000/new-path#footer'

// Protocol change
url.protocol = 'http';
console.log(url.href);
// 'http://example.com:3000/new-path#footer'

// Auth (username/password)
url.username = 'user';
url.password = 'pass';
console.log(url.href);
// 'http://user:pass@example.com:3000/new-path#footer'

// Clear port
url.port = '';
console.log(url.host); // 'example.com'

URLSearchParams#

// From URL
const url = new URL('https://example.com?name=alice&age=30');
const params = url.searchParams;

// Get values
console.log(params.get('name'));  // 'alice'
console.log(params.get('age'));   // '30'
console.log(params.get('city'));  // null

// Check existence
console.log(params.has('name'));  // true
console.log(params.has('city'));  // false

// Get all values (for repeated params)
const url2 = new URL('https://example.com?tag=js&tag=css&tag=html');
console.log(url2.searchParams.getAll('tag'));
// ['js', 'css', 'html']

// Standalone URLSearchParams
const params2 = new URLSearchParams('a=1&b=2');
const params3 = new URLSearchParams({ a: '1', b: '2' });
const params4 = new URLSearchParams([['a', '1'], ['b', '2']]);

Manipulating Query Parameters#

const params = new URLSearchParams();

// Add parameters
params.set('name', 'alice');
params.set('age', '30');
params.append('hobby', 'reading');
params.append('hobby', 'coding');

console.log(params.toString());
// 'name=alice&age=30&hobby=reading&hobby=coding'

// Delete parameter
params.delete('age');

// Sort alphabetically
params.sort();
console.log(params.toString());
// 'hobby=reading&hobby=coding&name=alice'

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

// Convert to object
const obj = Object.fromEntries(params);
// Note: loses duplicate keys

// Get all entries
const entries = [...params.entries()];
// [['hobby', 'reading'], ['hobby', 'coding'], ['name', 'alice']]

Building URLs#

// Build URL programmatically
function buildApiUrl(endpoint, params = {}) {
  const url = new URL(endpoint, 'https://api.example.com');

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

  return url.toString();
}

const apiUrl = buildApiUrl('/users', {
  page: 1,
  limit: 10,
  sort: 'name',
});
// 'https://api.example.com/users?page=1&limit=10&sort=name'

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

  path(segment) {
    this.url.pathname += segment.startsWith('/') ? segment : `/${segment}`;
    return this;
  }

  query(params) {
    Object.entries(params).forEach(([key, value]) => {
      this.url.searchParams.set(key, value);
    });
    return this;
  }

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

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

const url = new URLBuilder('https://example.com')
  .path('/api')
  .path('/users')
  .query({ page: 1, limit: 10 })
  .hash('results')
  .toString();

URL Validation#

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

console.log(isValidUrl('https://example.com')); // true
console.log(isValidUrl('not-a-url'));           // false

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

// Extract and validate
function parseUrl(urlString) {
  try {
    const url = new URL(urlString);
    return {
      valid: true,
      protocol: url.protocol,
      hostname: url.hostname,
      pathname: url.pathname,
      params: Object.fromEntries(url.searchParams),
    };
  } catch (error) {
    return {
      valid: false,
      error: error.message,
    };
  }
}

URL Encoding#

// encodeURIComponent - for values
const value = 'hello world & more';
const encoded = encodeURIComponent(value);
// 'hello%20world%20%26%20more'

// decodeURIComponent - decode values
const decoded = decodeURIComponent(encoded);
// 'hello world & more'

// encodeURI - for full URLs (preserves special chars)
const urlStr = 'https://example.com/path?name=hello world';
const encodedUrl = encodeURI(urlStr);
// 'https://example.com/path?name=hello%20world'

// URLSearchParams auto-encodes
const params = new URLSearchParams();
params.set('message', 'Hello & Goodbye');
console.log(params.toString());
// 'message=Hello+%26+Goodbye'

// File URLs
const filePath = '/Users/name/Documents/file name.txt';
const fileUrl = new URL(`file://${filePath}`);
console.log(fileUrl.href);
// Encoded properly

Practical Patterns#

// Parse and modify existing URL
function addQueryParam(urlString, key, value) {
  const url = new URL(urlString);
  url.searchParams.set(key, value);
  return url.toString();
}

// Remove query parameters
function removeQueryParams(urlString, ...keys) {
  const url = new URL(urlString);
  keys.forEach(key => url.searchParams.delete(key));
  return url.toString();
}

// Get clean URL (no query/hash)
function getCleanUrl(urlString) {
  const url = new URL(urlString);
  return `${url.origin}${url.pathname}`;
}

// Compare URLs ignoring order of params
function urlsEqual(url1, url2) {
  const a = new URL(url1);
  const b = new URL(url2);

  a.searchParams.sort();
  b.searchParams.sort();

  return a.href === b.href;
}

// Merge query parameters
function mergeQueryParams(urlString, newParams) {
  const url = new URL(urlString);

  Object.entries(newParams).forEach(([key, value]) => {
    if (value === null) {
      url.searchParams.delete(key);
    } else {
      url.searchParams.set(key, value);
    }
  });

  return url.toString();
}

Common Use Cases#

// API request builder
class ApiClient {
  constructor(baseUrl) {
    this.baseUrl = new URL(baseUrl);
  }

  buildUrl(path, params = {}) {
    const url = new URL(path, this.baseUrl);

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

    return url.toString();
  }

  async get(path, params) {
    const url = this.buildUrl(path, params);
    return fetch(url);
  }
}

// Pagination URLs
function paginationUrls(currentUrl, currentPage, totalPages) {
  const url = new URL(currentUrl);

  return {
    first: (() => {
      url.searchParams.set('page', '1');
      return url.toString();
    })(),
    prev: currentPage > 1 ? (() => {
      url.searchParams.set('page', String(currentPage - 1));
      return url.toString();
    })() : null,
    next: currentPage < totalPages ? (() => {
      url.searchParams.set('page', String(currentPage + 1));
      return url.toString();
    })() : null,
    last: (() => {
      url.searchParams.set('page', String(totalPages));
      return url.toString();
    })(),
  };
}

Best Practices#

Parsing:
✓ Use URL constructor for validation
✓ Use URLSearchParams for queries
✓ Handle parsing errors gracefully
✓ Validate protocols when needed

Building:
✓ Use URL for constructing URLs
✓ Let URLSearchParams handle encoding
✓ Build from trusted base URLs
✓ Sanitize user input

Encoding:
✓ Use encodeURIComponent for values
✓ Let URL handle most encoding
✓ Be careful with double-encoding
✓ Test with special characters

Avoid:
✗ String concatenation for URLs
✗ Manual encoding when not needed
✗ Assuming URL structure
✗ Ignoring edge cases

The URL module provides robust URL parsing and manipulation. Use the URL constructor for validation and modification, URLSearchParams for query string handling, and proper encoding functions for safety. Build URLs programmatically rather than concatenating strings.