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
const url = require('url');
// Using the modern URL class (WHATWG API)
const { 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 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);
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
// 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'
URLSearchParams API
The URLSearchParams API provides utility methods to work with the query string of a URL:
Example
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());
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
<html>
<body>
<h1>Summer</h1>
<p>I love the sun!</p>
</body>
</html>
winter.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 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:
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:
<p>I love the sun!</p>
http://localhost:8080/winter.html
Will produce this result:
<p>I love the snow!</p>
Best Practices
1. Always Validate and Sanitize URLs
Example
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
// 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
// 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'