Node.js URL Module
The Built-in URL Module
The URL module provides utilities for URL resolution and parsing.
It can be used to split up a web address into readable parts, construct URLs, and handle different URL components.
Getting Started
To include the URL module, use the require() method.
In modern Node.js (v10.0.0+), you can use either the legacy API or the newer URL class (WHATWG URL API):
Example
// Using the legacy API
const url = require('url');
// Using the modern URL class (WHATWG API)
const { URL } = require('url');
let url = require('url');
Parse an address with the url.parse() method, and it will return a URL object with each part of the address as properties:
Example
Split a web address into readable parts:
let url = require('url');
let adr = 'http://localhost:8080/default.htm?year=2017&month=february';
let q = url.parse(adr, true);
console.log(q.host);
console.log(q.pathname);
console.log(q.search);
let qdata = q.query;
console.log(qdata.month);
Try it Yourself »
URL Parsing and Formatting
URL Object Properties
When you parse a URL, you get a URL object with the following properties:
href: The full URL that was parsedprotocol: The protocol scheme (e.g., 'http:')host: The full host portion (e.g., 'example.com:8080')hostname: The hostname portion (e.g., 'example.com')port: The port number if specifiedpathname: The path section of the URLsearch: The query string including the leading ?query: Either the query string without the ?, or a parsed query objecthash: The fragment identifier including the #
Legacy API vs WHATWG URL API
Example
const { URL } = require('url');
// Using the WHATWG URL API (recommended for new code)
const myURL = new URL('https://example.org:8080/p/a/t/h?query=string#hash');
console.log(myURL.hostname); // 'example.org'
console.log(myURL.pathname); // '/p/a/t/h'
console.log(myURL.searchParams.get('query')); // 'string'
// Using the legacy API
const parsedUrl = require('url').parse('https://example.org:8080/p/a/t/h?query=string#hash');
console.log(parsedUrl.host); // 'example.org:8080'
console.log(parsedUrl.query); // 'query=string'
Try it Yourself »
URLSearchParams API
The URLSearchParams API provides utility methods to work with the query string of a URL:
Example
const { URL, URLSearchParams } = require('url');
const myURL = new URL('https://example.com/?name=Kai&age=30');
const params = new URLSearchParams(myURL.search);
// Get a parameter
console.log(params.get('name'));
// Add a parameter
params.append('city', 'Stavanger');
// Delete a parameter
params.delete('age');
// Convert to string
console.log(params.toString());
Run Example »
Node.js File Server
Now we know how to parse the query string, and in a previous chapter we learned how to make Node.js behave as a file server.
Let us combine the two, and serve the file requested by the client.
Create two html files and save them in the same folder as your node.js files.
summer.html
<!DOCTYPE html>
<html>
<body>
<h1>Summer</h1>
<p>I love the sun!</p>
</body>
</html>
winter.html
<!DOCTYPE html>
<html>
<body>
<h1>Winter</h1>
<p>I love the snow!</p>
</body>
</html>
Create a Node.js file that opens the requested file and returns the content to the client. If anything goes wrong, throw a 404 error:
demo_fileserver.js:
let http = require('http');
let url = require('url');
let fs = require('fs');
http.createServer(function (req, res) {
let q = url.parse(req.url, true);
let filename = "." + q.pathname;
fs.readFile(filename, function(err, data) {
if (err) {
res.writeHead(404, {'Content-Type': 'text/html'});
return res.end("404 Not Found");
}
res.writeHead(200, {'Content-Type': 'text/html'});
res.write(data);
return res.end();
});
}).listen(8080);
Remember to initiate the file:
Initiate demo_fileserver.js:
C:\Users\Your Name>node demo_fileserver.js
If you have followed the same steps on your computer, you should see two different results when opening these two addresses:
http://localhost:8080/summer.html
Will produce this result:
<h1>Summer</h1>
<p>I love the sun!</p>
http://localhost:8080/winter.html
Will produce this result:
<h1>Winter</h1>
<p>I love the snow!</p>
Best Practices
1. Always Validate and Sanitize URLs
Example
function isValidHttpUrl(string) {
try {
const url = new URL(string);
return url.protocol === 'http:' || url.protocol === 'https:';
} catch (err) {
return false;
}
}
console.log(isValidHttpUrl('https://example.com')); // true
console.log(isValidHttpUrl('ftp://example.com')); // false
2. Constructing URLs Safely
Example
const { URL } = require('url');
// Safe way to construct URLs
function createProfileUrl(domain, username) {
return new URL(`/users/${encodeURIComponent(username)}`, domain).href;
}
console.log(createProfileUrl('https://example.com', 'johndoe'));
// 'https://example.com/users/johndoe'
3. Handling Query Parameters
Example
const { URL } = require('url');
// Parse URL with query parameters
const url = new URL('https://example.com/search?q=node.js&lang=en');
// Get all parameters
console.log(url.searchParams.toString()); // 'q=node.js&lang=en'
// Get specific parameter
console.log(url.searchParams.get('q')); // 'node.js'
// Check if parameter exists
console.log(url.searchParams.has('lang')); // true
// Add new parameter
url.searchParams.append('page', '2');
console.log(url.href);
// 'https://example.com/search?q=node.js&lang=en&page=2'
