How to Use url.parse in Node.js: Syntax and Examples

In Node.js, you use url.parse from the built-in url module to break a URL string into its components like protocol, hostname, and path. Import the module with import { parse } from 'url' and call parse(urlString) to get an object with URL parts.

Syntax

The url.parse function takes a URL string and returns an object with its parts. It has this form:

• url.parse(urlString, parseQueryString = false, slashesDenoteHost = false)

Where:

• urlString: The URL you want to parse.
• parseQueryString: If true, the query part is parsed into an object.
• slashesDenoteHost: If true, treats // as host start.

javascript

import { parse } from 'url';

const parsedUrl = parse('https://example.com:8080/path?name=value#hash', true, false);

Example

This example shows how to parse a URL string and access its parts like protocol, hostname, port, pathname, query, and hash.

javascript

import { parse } from 'url';

const urlString = 'https://example.com:8080/path/to/page?name=alice&age=30#section1';
const parsed = parse(urlString, true);

console.log('Protocol:', parsed.protocol);
console.log('Host:', parsed.host);
console.log('Hostname:', parsed.hostname);
console.log('Port:', parsed.port);
console.log('Pathname:', parsed.pathname);
console.log('Query object:', parsed.query);
console.log('Hash:', parsed.hash);

Output

Protocol: https:
Host: example.com:8080
Hostname: example.com
Port: 8080
Pathname: /path/to/page
Query object: { name: 'alice', age: '30' }
Hash: #section1

Common Pitfalls

One common mistake is not setting the parseQueryString argument to true, which means the query stays a string instead of an object. Also, url.parse is legacy and Node.js recommends using the WHATWG URL class for new code.

Example of the wrong and right way to parse query:

javascript

import { parse } from 'url';

const urlStr = 'https://site.com/page?item=book&price=20';

// Wrong: query is a string
const wrongParsed = parse(urlStr);
console.log('Wrong query:', wrongParsed.query); // 'item=book&price=20'

// Right: query is an object
const rightParsed = parse(urlStr, true);
console.log('Right query:', rightParsed.query); // { item: 'book', price: '20' }

Output

Wrong query: item=book&price=20
Right query: { item: 'book', price: '20' }

Quick Reference

url.parse(urlString, parseQueryString, slashesDenoteHost)

• urlString: URL string to parse.
• parseQueryString: Boolean to parse query string into object.
• slashesDenoteHost: Boolean to treat // as host start.

Returns an object with properties like protocol, host, hostname, port, pathname, query, and hash.

Note: For modern code, prefer the URL class instead of url.parse.

Key Takeaways

Use url.parse(urlString, true) to get a parsed URL object with query as an object.

url.parse breaks a URL into parts like protocol, hostname, port, pathname, query, and hash.

Remember url.parse is legacy; prefer the modern URL class for new projects.

Set the second argument to true to parse the query string into an object automatically.

Always import parse from the built-in url module in Node.js.