Punycode Encoding in JavaScript
Encode and decode internationalized domain names with Punycode in Node.js — using the built-in url module.
Published:
Tags: Punycode JavaScript, Node.js punycode module, JavaScript IDN encoding
Punycode Encoding in JavaScript Part of our complete guide to this topic — see the full series. Internationalized domain names need Punycode conversion for DNS lookups and security checks. Here is how to handle IDN domains correctly in both Node.js and the browser. Punycode (RFC 3492) enables 1,900+ international domain extensions and supports 189 countries. --- All the tools discussed here are available for free at theproductguy.in — client-side, no sign-up required. What about The Built-In Approach: WHATWG URL API? The modern URL API (available in Node.js v10+ and all modern browsers) handles IDN automatically via Punycode encoding of the hostname. --- What about The npm Package? The deprecated Node.js built-in module was removed in Node.js v21. The npm package provides the same…
Frequently Asked Questions
How do I encode Punycode in Node.js?
The most straightforward approach uses the WHATWG URL API: new URL('https://' + domain).hostname. Node.js's built-in URL class automatically handles IDN by converting Unicode hostnames to Punycode. For full domain IDNA support, use the 'idna-uts46' or 'idna' npm package which implements the IDNA 2008 specification more completely.
What is the Node.js url module for IDN?
Node.js has a built-in 'url' module with two APIs: the legacy url.parse() (which does not handle IDN) and the WHATWG URL API (new URL()) which does handle IDN by Punycode-encoding the hostname. The WHATWG URL API is the recommended modern approach. The deprecated 'punycode' built-in module (removed from Node.js core in v21) was the earlier solution.
How do I decode a xn-- domain in JavaScript?
In the browser and Node.js, the URL API automatically displays Unicode when the domain is safe to display. To explicitly decode xn-- to Unicode for display purposes, you can use the 'punycode' npm package (not the deprecated Node.js built-in): import punycode from 'punycode/'; punycode.toUnicode('xn--mnchen-3ya.de') returns 'münchen.de'.
Is the punycode npm package still used?
Yes — the npm package 'punycode' (note: this is different from the deprecated Node.js built-in module) is actively maintained and widely used. It implements RFC 3492 Punycode encoding. Install with: npm install punycode. Import with: import punycode from 'punycode/'; (trailing slash to ensure you get the npm package, not the deprecated built-in).
How do I handle IDNs in a URL parser?
Always use the WHATWG URL API (available in Node.js v10+ and all modern browsers). It handles IDN transparently: the URL object's hostname property stores the Punycode form for DNS lookups, while display-oriented logic can call toUnicode() for the human-readable form. Never use the legacy url.parse() for IDN domains — it does not Punycode-encode the hostname.
All articles · theproductguy.in