If we want to promote accessing the new WHATWG URL from the global scope then maybe the code example as-is is ok, but otherwise, since this is a docs for the core URL module then it is somewhat confusing how to access since doing this won't work:

const URL = require('url')
const myURL = new URL('..')

@lirantal Yeah, since all supported Node.js versions have URL on the global object, I’d not document require('url').URL as the default way to access the URL constructor.

Maybe the Class: `URL` section could mention that this is an alternative way of accessing the class?

Exactly, so it depends what we want to promote :-)
If we want to promote users to access URL via the global object that's probably good as is, though I'd even then add a comment to the code to make it clear. Since the docs are inside this core module and the other examples clearly shows the require for the url module, it makes this one where the change is due, somewhat ambiguous. Maybe it's just me.

@lirantal Since nobody else has weighed in here yet: I’d say let’s not do this, and instead mention this as an alternative possibility for access in the URL constructor’s documentation section.

Sure. So would we replace this one https://github.com/nodejs/node/pull/32782/files#diff-dd182d238def46a3af0d112f617e8838L104 with the option I suggested or just add it as a note below it? I need an actual code example would be good.

@lirantal I think an explicit second example would be good. E.g.:

The URL constructor is accessible as a property on the global object. It can also be imported from the built-in url module:

console.log(URL === require('url').URL); // Prints 'true'.

@addaleax added it to the constructor example instead of the generic one on the intro.

all fixed up 👍

CI fails on Build from tarball / test-tarball-windows (pull_request) Failing after 51m — test-tarball-windows here: https://github.com/nodejs/node/actions/runs/87457793

Landed in 6b2e3af

Thanks Anna 👍