node:url

require('url')

The node:url module provides utilities for URL parsing, resolution, and manipulation. It supports both the legacy url.parse() API and the modern URL class that follows the WHATWG URL Standard. This module is essential for working with URLs in web servers, API clients, and any application that handles URLs.

The URL Class (Modern API)

The URL class provides a convenient and standards-compliant way to work with URLs.

Creating a URL Object

const { URL } = require('url');

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

console.log(myURL.href);
// "https://user:pass@example.com:8080/path/name?query=value#hash"

console.log(myURL.protocol);
// "https:"

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.username);
// "user"

console.log(myURL.password);
// "pass"

Modifying URL Components

const { URL } = require('url');

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

url.protocol = 'http:';
url.hostname = 'newhost.com';
url.port = '3000';
url.pathname = '/newpath';
url.search = 'key=value';

console.log(url.href);
// "http://newhost.com:3000/newpath?key=value"

Query String Manipulation

const { URL } = require('url');

const url = new URL('https://example.com/search?q=javascript&page=1');

// Get all parameters
console.log(url.searchParams.get('q'));      // "javascript"
console.log(url.searchParams.get('page'));    // "1"

// Set parameters
url.searchParams.set('q', 'typescript');
url.searchParams.append('lang', 'en');

console.log(url.href);
// "https://example.com/search?q=typescript&page=1&lang=en"

// Delete parameters
url.searchParams.delete('page');

console.log(url.href);
// "https://example.com/search?q=typescript&lang=en"

Legacy API

The legacy API uses url.parse() and url.format() functions.

Parsing a URL

const url = require('url');

const parsed = url.parse('https://user:pass@example.com:8080/path?q=1#hash');

console.log(parsed);
// {
//   protocol: 'https:',
//   auth: 'user:pass',
//   hostname: 'example.com',
//   port: '8080',
//   path: '/path?q=1',
//   pathname: '/path',
//   query: 'q=1',
//   hash: '#hash'
// }

Resolving Relative URLs

const url = require('url');

console.log(url.resolve('/one/two', 'three'));
// "/one/three"

console.log(url.resolve('/one/two/', 'three'));
// "/one/two/three"

console.log(url.resolve('http://example.com/', '/one'));
// "http://example.com/one"

console.log(url.resolve('http://example.com/a', '../b'));
// "http://example.com/b"

Examples

Building URLs from Parts

const { URL } = require('url');

function buildUrl(base, params) {
  const url = new URL(base);
  Object.entries(params).forEach(([key, value]) => {
    url.searchParams.append(key, value);
  });
  return url.toString();
}

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

console.log(apiUrl);
// "https://api.example.com/users?page=1&limit=10&sort=name"

Extracting Information from Request URLs

const { URL } = require('url');

function parseRequestUrl(reqUrl, baseUrl = 'http://localhost:3000') {
  const url = new URL(reqUrl, baseUrl);
  
  return {
    pathname: url.pathname,
    params: Object.fromEntries(url.searchParams),
    isJson: url.pathname.endsWith('.json') || url.searchParams.get('format') === 'json'
  };
}

const result = parseRequestUrl('/api/users?page=2&active=true');
console.log(result);
// { pathname: '/api/users', params: { page: '2', active: 'true' }, isJson: false }

URL Validation

const { URL } = require('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
console.log(isValidUrl('ftp://files.example'));  // true

File URL Handling (Node.js specific)

const { URL } = require('url');

// Convert file path to file:// URL
const fileUrl = new URL('file:///Users/name/project/file.txt');
console.log(fileUrl.pathname);

// Convert file:// URL to path
const path = fileUrl.pathname;
console.log(path);  // "/Users/name/project/file.txt" (platform-specific)

Important Notes

• Always validate URLs before using them, especially when dealing with user input.
• The URL class handles internationalized domain names (IDN) automatically.
• The searchParams object is mutable and automatically updates the search property.
• For server-side URL parsing from HTTP requests, combine with node:http or node:https.

See Also

• Http::Request — HTTP server and client
• Https::Request — HTTPS server and client