Introduction

I started seeing punycode DeprecationWarnings whenever I served or deployed my Hexo blog from some time:

(node:39714) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.

After some digging, I found that this issue occurs when using Node.js version 21. I wasn’t keen on downgrading, so I fought my way through and managed to resolve it.

Conclusion

Long story short, the issue was caused by outdated dependencies in some plugins used in my Hexo.

[Case 1] A manually created package had an outdated devDependency
- [Solution 1-1] Update the dependencies manually in the package’s package.json
- [Solution 1-2] If devDependencies are unnecessary, remove them entirely
EX) A customized hexo-generator-searchdb plugin
[Case]
- I had made several modifications to my blog’s setup to support a bilingual (English/Korean) environment. One of these tweaks was modifying the search.xml generation to store the post’s language, and use it for search.
  ~~If the current site language is Korean, Korean-written posts have highest search priority.~~
- To achieve this, I copied the entire hexo-generator-searchdb source code into source/js/ and used it as a local package under the name hexo-generator-searchdb-custom.
  Then change the package setting like this:
  1
  2
  3
  "dependencies": {
  "hexo-generator-searchdb": "file:source/js/hexo-generator-searchdb-custom"
  }
[Problem]
- The problem was that running npm install also installed devDependencies of the local package.
  - IDK why, but the default --production flag which prevents devDependencies from being installed when using external packages didn’t seem to apply to local packages.
  - Anywhy, this package included eslint@7.32.0, which still used punycode in the old fashion.
[Solution]
- Since I didn’t actually need the devDependencies, I simply deleted them all from the local package.
- Alternatively, I could have updated hexo-generator-searchdb-custom/package.json as follows:
  1
  2
  3
  4
  "devDependencies": {
  "eslint": "^9.18.0",
  "@next-theme/eslint-config": "^0.0.4"
  }
[Case 2] An outdated package in dependencies within installed package
- [Solution 2-1] Use override to enforce a newer dependency version
- [Solution 2-2] Modify the punycode-related code in node_modules
  ~~Not ideal, but sometimes there's no other way...~~
EX) hexo-renderer-markdown-it plugin
[Case]
- Right now, my blog renders Markdown using the hexo-renderer-markdown-it plugin.
  - Since I use KaTex for math rendering, this plugin is recommended over the default hexo-renderer-markdown^[1].
- And the hexo-renderer-markdown-it plugin uses markdown-it@13.0.2.
[Problem]
- markdown-it@13.0.2 loads punycode in old way:
  - Instead of const punycode = require('punycode'), it should use
    const punycode = require('punycode/')^[2].
- Thus I should override the dependency to a newer version, or update the punycode-related code in node_modules by myself.
- The real problem was that updating markdown-it to version 14.0.0+ broke hexo-renderer-markdown-it… ~~I didn't want to spend time fixing it.. bc I've never studied Node.js...;-;~~
  
  [Solution]
- So I manually edited node_modules/hexo-renderer-markdown-it/node_modules/markdown-it/lib/index.js:
  1
  2
  // const punycode = require('punycode'); // Original
  const punycode = require('punycode/'); // Fixed
  - ~~What is the authors feeling when the problem solved only with a single slash? (1000)~~
  - Since the above code use punycode in node_modules, you’ll need to run npm install punycode --save if you haven’t already.
- To avoid manually editing it every time, you can automate it using a postinstall script (see below).

How I Got Resolved

The conclusion is just a conclusion, and I’m sure that most will get the deprecation issue from the other packages. Therefore, I wrote down the process of how I solved the problem in the stream of consciousness.

Check Status

If I remember correctly, the first thing I did was to check the version of Node.js.

1 2	$ node -v v21.7.3

Downgrading might have fixed it, but my pride wouldn’t allow it.
(Not at all actually. I just thought the latter will be better since I don’t have any knowledge about the difference between v20 and v21 in Node.js)

punycode vs. punycode/

Googling “npm punycode deprecation” and so on led me to realize that some packages that use punycode cause the warning due to the old way of importing it.

So, if you read the punycode GitHub readme^[2:1], it roughly says:

Install punycode
Use require('punycode/'), not require('punycode')

to avoid the warning.
~~Honestly, the two lines aren’t that different in my eyes. I just thought as they’re similar to a gap between from.utils import * and from.utils import * in python. Then I skipped it. haha~~

punycode dependency

Anyway, for that reason, I tried to find all modules that use punycode in my project. Let’s go to the root directory and look for the inheritance of the punycode with npm ls punycode.

$ npm ls punycode
hexo-blog@0.0.1 /root/directory/
├─┬ hexo-generator-searchdb-custom@1.4.1 -> /root/directory/node_modules/hexo-generator-searchdb-custom
│ └─┬ eslint@7.32.0
│   └─┬ ajv@cant.remember.0
│     └─┬ uri-js@cant.remember.0
│       └── punycode@cant.remember.0

I roughly got those results. (I don’t remember the exact version numbers)

As you can see, hexo-generator-searchdb-custom that uses eslint that uses uri-js that uses punycode was the problem. lol

Since I already had found lots of googling results about eslint, ajv, or uri-js packages, I also runned npm ls [package-name] for them to find the punycode dependency.

In sum, I found the old-versioned eslint dependency in two packages:

hexo-generator-searchdb-custom
hexo-generator-sitemap-custom

Fix (1)

At first, I opened the package.json of each package because I thought I could update the versions of these packages to the latest. But what I found was that both of them had eslint as a devDependencies, not dependencies.

As you can imagine from its name, both packages are the local packages that I customized from the original plugins. I had to fix almost all of the existing packages overall, so I just replicated them locally, modified them, and used them as below, and that caused the problem.

"dependencies": {
  "hexo-generator-searchdb": "file:source/js/hexo-generator-searchdb-custom",
  "hexo-generator-sitemap": "file:source/js/hexo-generator-sitemap-custom"
}

IDK why but when I run npm install, it also installed the devDependencies of the local package.

I guess the --production option of npm install doesn’t work for local packages.
Gave up on finding the exact reason nor the proper solution

I didn’t actually need the devDependencies since I just copied the original package for convenience. So I just deleted devDependencies inside package.json from each local package.

Then run below commands to reinstall whole packages:

1
2
3

$ rm -r node_modules
$ rm package-lock.json
$ npm install

Fix (2)

I thought it would be solved then… but Warning appeared again, and I was about to throw my laptop away for real ~~since it took me two days until here…~~

So I just emptied my mind and decided to find all js files that use punycode with find command.
~~its quite ignorant, but I didn’t have any other ideas:D~~

1 2	$ cd node_modules $ find . -type f -name "*.js" -exec grep -H "punycode" {} \;

In the middle of bunch of results, there was a code like this:
./hexo-renderer-markdown-it/node_modules/markdown-it/lib/index.js: var punycode = require('punycode');
x
Since I found one, I opened the file with the intention of modifying it one by one from here.

The file lib/index.js of markdown-it@13.0.2 installed inside hexo-renderer-markdown-it seemed to use punycode the old way.

So I just add a slash to the end and saved it:

1 2	// const punycode = require('punycode'); // Original const punycode = require('punycode/'); // Fixed

Then I ran hexo server -o again, and this time, it said punycode is not installed.
This is because punycode/ implies the punycode in the node_modules, so I installed it with npm i punycode --save.

Finally, I ran the server again, and the DeprecationWarning didn’t appear anymore.

Phew! I don’t have to throw my laptop away anymore!

Postinstall Script

By the way, modifying the code in node_modules was a bit annoying, and also was not seem to be a good practice. So I searched a little and soon found the usage of postinstall script.

It is reallllllly simple.

Install the patch-package package.
1
$ npm install patch-package --save-dev
Find the code that you want to fix in node_modules and fix it.
- Already fixed, so skip

Add the postinstall script to package.json.

1
2
3

"scripts": {
  "postinstall": "patch-package"
}

Save the modified file as a patch
1
$ npx patch-package [package-name]
Caution) Since I modified the package inside the package, if I run npx patch-package hexo-renderer-markdown-it, a message saying that ⁉️ There don't appear to be any changes. will appear.
In this case, you should run something like npx patch-package hexo-renderer-markdown-it/markdown-it instead.
Done!
- During the 4, the patch file will be created in patches directory.
- Now you don’t need to manually modify it anymore since the patches in that folder will be applied automatically when you run npm install.

P.S.

Can’t believe to had such a long and hard time just for a single warning message… I really shouldn’t dig up Node.js. No talent.🫠
I also tried the “overrides” method to update the markdown-it version later, but it didn’t work. It’ll be good to try overriding since the method is really easy^[3].

References

Butterfly document - Theme Configuration # Math (link) ↩︎
Github - mathiasbynens/punycode.js (link) ↩︎ ↩︎
npm Docs - package.json (link) ↩︎