Punycode Converter

Common errors

• Error: Cannot find module 'punycode'

  cause Attempting to `require('punycode')` in a Node.js environment where the built-in module is not available or has been overridden by the npm package without the correct import path.
  fix If you've installed the `punycode` npm package, ensure you are importing it with a trailing slash: `const punycode = require('punycode/');`.

• SyntaxError: Unexpected token ... (or similar ES2015+ syntax error)

  cause Using `punycode` v2.0.0 or higher in an environment that does not fully support ES2015+ features.
  fix Upgrade your Node.js version to v6 or higher, or use a modern browser. If backward compatibility for older runtimes is essential, downgrade to `punycode` v1.4.1.

Warnings

• breaking Version 2.0.0 and above dropped support for older JavaScript environments. It targets Node.js v6+ and modern browsers, requiring ES2015+ features.
  Fix: For compatibility with older runtimes (Rhino, Ringo, Narwhal, older browsers), use `punycode` v1.4.1. Otherwise, ensure your environment supports ES2015+.
• gotcha In Node.js, the userland `punycode` package from npm can conflict with Node.js's deprecated built-in `punycode` module.
  Fix: Always use `require('punycode/')` (with the trailing slash) to explicitly load the npm package. Avoid `require('punycode')` if you intend to use the userland module, as it will load the built-in one.
• deprecated The `punycode` module bundled with Node.js itself has been deprecated (soft-deprecated from v7) and is no longer recommended for new projects. It is advised to use the standalone npm package.
  Fix: Install the `punycode` npm package via `npm install punycode` and import it using `require('punycode/')` or `import punycode from 'punycode';`.

Install

• npm install punycode npm
• yarn add punycode yarn
• pnpm add punycode pnpm

Imports

• punycode
  wrong:

  const punycode = require('punycode');

  correct:

  const punycode = require('punycode/');

  In Node.js, `require('punycode')` refers to the deprecated built-in module. Always use `require('punycode/')` (with the trailing slash) to import the userland npm package.
• punycode
  wrong:

  import { decode, encode } from 'punycode';

  correct:

  import punycode from 'punycode';

  The library primarily exposes a default object with all its methods. While it ships as both CommonJS and ES Modules, direct named imports are not the intended pattern for the main functions.
• toASCII
  wrong:

  import { toASCII } from 'punycode';
  toASCII('mañana.com');

  correct:

  const punycode = require('punycode/');
  punycode.toASCII('mañana.com');

  Methods like `toASCII` are properties of the default `punycode` object, not direct named exports.

Quickstart

This quickstart demonstrates how to encode and decode internationalized domain names (IDN) and individual Unicode string parts using `punycode.js`.

const punycode = require('punycode/');

// Encode a Unicode domain name to Punycode
const unicodeDomain = 'mañana.com';
const punycodeDomain = punycode.toASCII(unicodeDomain);
console.log(`Unicode domain: ${unicodeDomain}`);
console.log(`Punycode domain: ${punycodeDomain}`);

// Decode a Punycode domain name back to Unicode
const decodedUnicodeDomain = punycode.toUnicode(punycodeDomain);
console.log(`Decoded Unicode domain: ${decodedUnicodeDomain}`);

// Encode/decode individual string parts
const unicodePart = '☃-⌘';
const punycodePart = punycode.encode(unicodePart);
console.log(`Unicode part: ${unicodePart}`);
console.log(`Punycode part: ${punycodePart}`);

const decodedUnicodePart = punycode.decode(punycodePart);
console.log(`Decoded Unicode part: ${decodedUnicodePart}`);