Docs: deprecated `url.parse()` call used in custom server example

[altendky]

What is the documentation issue?

the legacy url api is deprecated. i expect that deprecated APIs should not be encouraged in examples.

https://nodejs.org/api/deprecations.html#DEP0116

The legacy URL API is deprecated. This includes url.format(), url.parse(), url.resolve(), and the legacy urlObject. Please use the WHATWG URL API instead.

this is one example case. others should be searched for in this file and beyond if a change is made.

https://github.com/vercel/next.js/blob/78660a53864b8dfff75e8e122cc1db5e8a8d0e4b/docs/01-app/02-guides/custom-server.mdx?plain=1#L29-L32

the parsedUrl parameter for RequestHandler is optional.

https://github.com/vercel/next.js/blob/78660a53864b8dfff75e8e122cc1db5e8a8d0e4b/packages/next/src/server/next.ts#L64-L68

i would (with minimal next.js experience...) suggest simply removing the parsing entirely from the example or updating to the whatwg url api. if there is agreement on the path forward i could provide a pr for consideration.

or... maybe you'll tell me why this is nonsense and i'll learn a little something. :] thanks for your time.

Is there any context that might help us understand?

i started exploring this situation after i got the following (slightly snipped) traceback when running code similar to the example.

(node:3243635) [DEP0169] DeprecationWarning: `url.parse()` behavior is not standardized and prone to errors that have security implications. Use the WHATWG URL API instead. CVEs are not issued for `url.parse()` vulnerabilities.
    at urlParse (node:url:136:13)
    at Server.<anonymous> (file:///home/altendky/repos/<snip>/server.js:38:21)
    at Server.emit (node:events:508:28)
    at parserOnIncoming (node:_http_server:1186:12)
    at HTTPParser.parserOnHeadersComplete (node:_http_common:123:17)

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/pages/guides/custom-server

[icyJoseph]

Duplicate: https://github.com/vercel/next.js/issues/83183

I'll get around to fix it, or if someone wants to submit a PR 🙏

Note that this is a node 24 warning, but yeah, since the suggestion in #83183 got merged we can use either of the getURL options listed here:

• https://nodejs.org/docs/latest/api/url.html#urlparseurlstring-parsequerystring-slashesdenotehost

[azadgupta1]

I’d like to take this issue — may I work on it?

[ashishs10]

Hi! 👋

While reviewing the Next.js custom server documentation, I noticed that the example still uses Node’s deprecated url.parse() API, which triggers DEP0116 and DEP0169 warnings.

Node now recommends using the WHATWG URL API instead, and based on the RequestHandler type, the parsedUrl parameter is optional.

I see two possible fixes:

Remove URL parsing entirely, since it’s not required for the example.

Replace the legacy API with new URL(), following the WHATWG approach.

I’m happy to open a PR to address this. Before I proceed, do you have a preferred direction?

Thanks!

[altendky]

while the warning is indeed more recent, note that the actual ... dispreference (?) came long before that

https://nodejs.org/docs/latest/api/url.html#urlparseurlstring-parsequerystring-slashesdenotehost

Version	Changes
v19.0.0, v18.13.0	Documentation-only deprecation.
v15.13.0, v14.17.0	Deprecation revoked. Status changed to "Legacy".
v11.0.0	The Legacy URL API is deprecated. Use the WHATWG URL API.

anyways, not a big deal there.

i'm curious, is it necessary to switch to the whatwg url option vs. just deleting the parsing entirely and not passing anything to the option RequestHandler parameter parsedUrl? does this cause problems? my local dev environment runs and works, but again, i'm no expert here.

 const server = createServer((req, res) => {
-  const parsedUrl = parse(req.url, true);
-  handle(req, res, parsedUrl);
+  handle(req, res);
 });

@azadgupta1, thanks for the interest! once we understand what pattern the example should be changed to i would love to see a pr from you. :] seems like icyJoseph is on board with that too.

[altendky]

oops, didn't reload the page... looks like ashishs10 is on it already... thanks! i think my questions about simply removing the parsing stand.

[icyJoseph]

So like tracing what happens with getRequestHandler and the handle it return, we see that, the parsedUrl param is optional

• https://github.com/vercel/next.js/blob/42690262d69988cd95e8317a725095f8f75f85cd/packages/next/src/server/base-server.ts#L1625-L1630

• https://github.com/vercel/next.js/blob/42690262d69988cd95e8317a725095f8f75f85cd/packages/next/src/server/base-server.ts#L845-L849

And that later in the handler implementation, we do a check - if undefined, or in string shape, the next-server does the parsing again.

• https://github.com/vercel/next.js/blob/42690262d69988cd95e8317a725095f8f75f85cd/packages/next/src/server/base-server.ts#L921-L925

• https://github.com/vercel/next.js/blob/42690262d69988cd95e8317a725095f8f75f85cd/packages/next/src/server/base-server.ts#L950-L957

So indeed, it should be safe to just call handle(req, res) - I guess you'd undo this if you wanted to modify the query param object in some fashion.

[ashishs10]

Thanks for the update! I just saw that the PR has been merged — appreciate the quick resolution. I’ll look for other issues to contribute to. Happy to help wherever needed!