`docusaurus start` command shows DeprecationWarning: The `punycode` module is deprecated.

[mamiu]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

When starting a dev server of the latest version of Node (v22.1.0) and Docusaurus (v3.3.2) with npm start (docusaurus start) I'll get the following warning:

DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.

This is due to the fact that docusaurus/core has serve-handler as a dependency.
And serve-handler itself depends on fast-url-parser which seems to be the root cause of this warning.

Is there anything Docusaurus can do to fix this or does the serve-handler project have to refactor its code from fast-url-parser to Node's native url module instead?

Reproducible demo

No response

Steps to reproduce

npx create-docusaurus@latest my-website classic
cd my-website
npm run start

Expected behavior

Don't show any warnings in the console.

Actual behavior

When starting a dev server of the latest version of Node (v22.1.0) and Docusaurus (v3.3.2) with npm start (docusaurus start) I'll get the following warning:

DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.

Your environment

No response

Self-service

• I'd be willing to fix this bug myself.

[slorber]

Thanks

Normally we'd wait for serve-handler to update and fix the problem. Unfortunately, I doubt serve-handler is well-maintained these days, and not sure a fix will be published. We'd probably have to patch it ourselves.

---

It's a bit risky to change server implementation in a minor release, but we might drop serve-handler in a major if we find a good alternative. I don't know the current landscape of alternatives to serve a static deployment.

There's Nitro, but its primary use-case does not look like to be static deployments, although it could be interesting in the future if we want to add support for Docusaurus server-side features (do we?).

[mamiu]

@slorber I agree that serve-handler is not well-maintained anymore. But also don't know of any good alternatives.

[...] if we want to add support for Docusaurus server-side features (do we?).

I would absolutely love to see Docusaurus moving into this direction (as long as they stay optional).
With server-side features there would be endless possibilities to make Docusaurus way better than it already is.

[jamiecropley]

Is this anything to worry about or can I just ignore this warning for my docusaurus site?

[g1eny0ung]

Encounter the same problem too. If you are using pnpm as the package manager, simply run pnpm patch fast-url-parser@1.1.3 and update the require('punycode') to require('punycode/'), then run pnpm patch-commit ... to solve it temporarily.

More details: petkaantonov/urlparser#20.

[ammoniak]

The warning turned into an error. Was this fixed?

[g1eny0ung]

@ammoniak I upgraded to the latest version (v3.6.x - v3.7.0), and this problem has disappeared. My environment is node: v20.18.1.

[ammoniak]

I just tried it again on a different machine and you are right, it works. I digged a little deeper and it seems to be a npm cache issue. sorry, I should have checked that first.