A modern TypeScript implementation of Punycode (RFC 3492) with full RFC 5891 support. This library helps you convert Unicode domain names to ASCII (Punycode) and back.

• 🔄 Bidirectional Conversion - Convert between Unicode and Punycode seamlessly
• 📧 Email Support - Handles email addresses with Unicode domains
• 💪 Type-Safe - Full TypeScript support with comprehensive type definitions
• 🌐 RFC Compliant - Implements RFC 3492 and RFC 5891 specifications
• 🧪 Well-Tested - Comprehensive test suite ensuring reliability
• 📦 Zero Dependencies - Lightweight and self-contained
• 🔍 Unicode 15.1 - Support for the latest Unicode standard

# Using npm
npm install ts-punycode

# Using yarn
yarn add ts-punycode

# Using pnpm
pnpm add ts-punycode

# Using bun
bun add ts-punycode

import punycode from 'ts-punycode'

// Convert Unicode to Punycode
punycode.encode('münchen') // Returns 'mnchen-3ya'

// Convert Punycode to Unicode
punycode.decode('mnchen-3ya') // Returns 'münchen'

// Convert Domain Names
punycode.toASCII('münchen.de') // Returns 'xn--mnchen-3ya.de'
punycode.toUnicode('xn--mnchen-3ya.de') // Returns 'münchen.de'

// Handle Email Addresses
punycode.toASCII('user@münchen.de') // Returns 'user@xn--mnchen-3ya.de'
punycode.toUnicode('user@xn--mnchen-3ya.de') // Returns 'user@münchen.de'

import punycode from 'ts-punycode'
// import { punycode } from 'ts-punycode'

// Working with Unicode Code Points
const codePoints = punycode.ucs2.decode('☃') // Returns [9731]
const string = punycode.ucs2.encode([9731]) // Returns '☃'

// Version Information
console.log(punycode.version) // Returns current version

• encode(input: string): string

  Converts a string of Unicode symbols to a Punycode string of ASCII-only symbols.

• decode(input: string): string

  Converts a Punycode string of ASCII-only symbols to a string of Unicode symbols.

• toASCII(input: string): string

  Converts a Unicode string representing a domain name or email address to Punycode.

• toUnicode(input: string): string

  Converts a Punycode string representing a domain name or email address to Unicode.

• ucs2.decode(string: string): number[]

  Creates an array containing the numeric code points of each Unicode character.

• ucs2.encode(codePoints: number[]): string

  Creates a string based on an array of numeric code points.

The library throws RangeError with descriptive messages for various error conditions:

• Overflow: When input needs wider integers to process
• Not Basic: When encountering illegal input >= 0x80 (not a basic code point)
• Invalid Input: For general invalid input conditions

Please see CONTRIBUTING for details.

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Stacks OSS will always stay open-sourced, and we will always love to receive postcards from wherever Stacks is used! And we also publish them on our website. Thank you, Spatie.

Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

• Mathias Bynens
• Punycode.js
• Chris Breuer

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙