Core Modules

Node.js url and querystring

The URL class parses and builds URLs safely, and URLSearchParams handles query strings including encoding. Both are global in modern Node and match the browser APIs exactly.

What is url and querystring in Node.js?

The URL class parses and builds URLs safely, and URLSearchParams handles query strings including encoding. Both are global in modern Node and match the browser APIs exactly.

Why url and querystring matters

URLs arrive from users, webhooks and third-party redirects, and every one of them can contain spaces, ampersands, plus signs and non-English characters. Hand-built strings get these wrong; the URL class gets them right and also validates the input.

url and querystring example

Parsing and building URLs

JavaScript

const url = new URL('https://myinternships.in/jobs?city=Pune&page=2');

url.hostname;                       // myinternships.in
url.pathname;                       // /jobs
url.searchParams.get('city');       // 'Pune'
url.searchParams.set('page', '3');
url.searchParams.append('role', 'frontend developer');

url.toString();
// https://myinternships.in/jobs?city=Pune&page=3&role=frontend+developer

Reading a request URL and building an outbound one

JavaScript

// resolve a request URL against the host
const reqUrl = new URL(req.url, `http://${req.headers.host}`);
const page = Number(reqUrl.searchParams.get('page') ?? 1);

// build an outbound API call safely
const api = new URL('https://api.example.com/v1/search');
api.searchParams.set('q', 'frontend intern & designer');   // encoded for you
api.searchParams.set('city', 'Bengaluru');
await fetch(api);

// repeated keys: ?tag=react&tag=node
reqUrl.searchParams.getAll('tag');   // ['react', 'node']

req.url on a Node http server is only the path and query, so it must be resolved against a base before the URL class will accept it. Once parsed, searchParams handles encoding, decoding and repeated keys correctly.

Key points to remember

URLSearchParams encodes values automatically — no manual encodeURIComponent needed.
Building URLs by string concatenation is how injection and encoding bugs happen.
The legacy url.parse() and querystring module are deprecated in favour of the URL class.
new URL() throws on an invalid URL, which makes it a validator as well as a parser.
The same API exists in browsers, so this knowledge transfers to front-end code.

What the URL class gives you

Property	For https://site.in:8080/jobs/12?city=Pune#apply
protocol	https:
hostname	site.in
port	8080
pathname	/jobs/12
search	?city=Pune
searchParams	a URLSearchParams object
hash	#apply
origin	https://site.in:8080

Common mistakes with url and querystring

Passing a relative path to new URL() without a base, which throws ERR_INVALID_URL.
Using get() when a parameter can repeat — it returns only the first value; use getAll().
Treating searchParams values as numbers; every one is a string.

💡

Wrap new URL() in try/catch when the input came from a user or a webhook — treating the throw as "invalid URL" is simpler and safer than writing a validation regular expression.