> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nodejs/userland-migrations/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://nodejs.org/api/deprecations.html#DEP0116) for more details.

## Usage

Run this codemod with:

```bash theme={null}
npx codemod nodejs/node-url-to-whatwg-url
```

## Before/After

### url.parse() to new URL()

```diff theme={null}
- 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()

```diff theme={null}
- 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:

```js theme={null}
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.

<Warning>
  The WHATWG URL API doesn't support all legacy `url` module features. Review the caveats section and test thoroughly after migration.
</Warning>

<Tip>
  The WHATWG URL API is standardized across browsers and Node.js, making your code more portable and compatible with modern web standards.
</Tip>