Node.js URL to WHATWG URL

Migrate from legacy Node.js url module to the modern WHATWG URL API (DEP0116)

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(/^\[|\]$/, '');

url.format() to URL.toString()

- 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.