This recipe converts legacy Node.js url module usage to the modern WHATWG URL API, replacing methods like url.parse() and url.format() with the standard URL class.
Deprecation
Node.js deprecated the legacy url module methods in favor of the WHATWG URL Standard.
See DEP0116 for more details.
Usage
Run this codemod with:
npx codemod nodejs/node-url-to-whatwg-url
Before/After
url.parse() to new URL()
- const url = require('node:url');
- const myURL = url.parse('https://example.com/path?query=string#hash');
+ const myURL = new URL('https://example.com/path?query=string#hash');
- const { auth } = myURL;
+ const auth = `${myURL.username}:${myURL.password}`;
- const urlAuth = myURL.auth;
+ const urlAuth = `${myURL.username}:${myURL.password}`;
- const { path } = myURL;
+ const path = `${myURL.pathname}${myURL.search}`;
- const urlPath = myURL.path;
+ const urlPath = `${myURL.pathname}${myURL.search}`;
- const { hostname } = myURL;
+ const hostname = myURL.hostname.replace(/^\[|\]$/, '');
- const urlHostname = myURL.hostname;
+ const urlHostname = myURL.hostname.replace(/^\[|\]$/, '');
- const url = require('node:url');
- url.format({
+ const myUrl = new URL('https://example.com/some/path?page=1&format=json').toString();
- protocol: 'https',
- hostname: 'example.com',
- pathname: '/some/path',
- query: {
- page: 1,
- format: 'json',
- },
- });
What It Does
- Replaces
url.parse() with new URL()
- Replaces
url.format() with new URL().toString()
- Transforms legacy URL properties to WHATWG equivalents
- Updates imports to remove the
url module when no longer needed
Property Mapping
Legacy url.parse() | WHATWG URL API | |
|---|
auth | ${url.username}:${url.password} | |
path | ${url.pathname}${url.search} | |
hostname | `url.hostname.replace(/^[ | ]$/, ”)` |
protocol | url.protocol | |
pathname | url.pathname | |
search | url.search | |
hash | url.hash | |
Caveats
url.resolve() Migration
The url.resolve() method is not directly translatable to the WHATWG URL API. You may need to implement custom logic:
function resolve(from, to) {
const resolvedUrl = new URL(to, new URL(from, 'resolve://'));
if (resolvedUrl.protocol === 'resolve:') {
// `from` is a relative URL.
const { pathname, search, hash } = resolvedUrl;
return pathname + search + hash;
}
return resolvedUrl.toString();
}
resolve('/one/two/three', 'four'); // '/one/two/four'
resolve('http://example.com/', '/one'); // 'http://example.com/one'
resolve('http://example.com/one', '/two'); // 'http://example.com/two'
Non-Standard Properties
If you’re using url.parse().auth, url.parse().path, or bracket-wrapped IPv6 hostnames, you’ll need to manually construct these values from WHATWG URL properties as shown in the examples above.
The WHATWG URL API doesn’t support all legacy url module features. Review the caveats section and test thoroughly after migration.
The WHATWG URL API is standardized across browsers and Node.js, making your code more portable and compatible with modern web standards.
