@phantom/base64url

Isomorphic base64url encoding/decoding utilities that work in both browser and Node.js environments.

Installation

npm install @phantom/base64url

Features

• 🌐 Isomorphic - Works in both browser and Node.js
• 🚀 Zero dependencies - Lightweight and fast
• 📱 Modern & Legacy - Supports both modern APIs and older browsers
• 🔒 URL-safe - Uses base64url format (RFC 4648)
• 📦 TypeScript - Full type support included

Usage

import { base64urlEncode, base64urlDecode, stringToBase64url, base64urlDecodeToString } from "@phantom/base64url";

// Encode string to base64url
const encoded = stringToBase64url("Hello World");
console.log(encoded); // "SGVsbG8gV29ybGQ"

// Decode base64url to string
const decoded = base64urlDecodeToString(encoded);
console.log(decoded); // "Hello World"

// Encode Uint8Array to base64url
const bytes = new Uint8Array([72, 101, 108, 108, 111]);
const encodedBytes = base64urlEncode(bytes);
console.log(encodedBytes); // "SGVsbG8"

// Decode base64url to Uint8Array
const decodedBytes = base64urlDecode(encodedBytes);
console.log(decodedBytes); // Uint8Array([72, 101, 108, 108, 111])

API Reference

base64urlEncode(data: string | Uint8Array | ArrayLike<number>): string

Encodes data to base64url format.

• data: String, Uint8Array, or ArrayLike data to encode
• Returns: base64url encoded string (no padding, URL-safe)

base64urlDecode(str: string): Uint8Array

Decodes base64url string to Uint8Array.

• str: base64url encoded string
• Returns: decoded Uint8Array

stringToBase64url(str: string): string

Encodes UTF-8 string to base64url format.

• str: UTF-8 string to encode
• Returns: base64url encoded string

base64urlDecodeToString(str: string): string

Decodes base64url string to UTF-8 string.

• str: base64url encoded string
• Returns: decoded UTF-8 string

Base64url Format

Base64url is a URL-safe variant of Base64 encoding defined in RFC 4648:

• Uses - instead of +
• Uses _ instead of /
• Removes padding (=) characters
• Safe to use in URLs, filenames, and HTTP headers

Browser Compatibility

• Modern browsers: Uses native btoa/atob and TextEncoder/TextDecoder
• Legacy browsers: Provides fallbacks for older environments
• Node.js: Uses Buffer for optimal performance

Examples

JWT Token Handling

import { stringToBase64url, base64urlDecodeToString } from "@phantom/base64url";

const payload = JSON.stringify({
  sub: "1234567890",
  name: "John Doe",
  iat: 1516239022,
});

const encodedPayload = stringToBase64url(payload);
console.log(`JWT payload: ${encodedPayload}`);

const decodedPayload = base64urlDecodeToString(encodedPayload);
console.log(JSON.parse(decodedPayload));

Binary Data Encoding

import { base64urlEncode, base64urlDecode } from "@phantom/base64url";

// Encode binary data
const binaryData = new Uint8Array([0xff, 0xfe, 0xfd, 0xfc]);
const encoded = base64urlEncode(binaryData);
console.log(encoded); // URL-safe encoded string

// Decode back to binary
const decoded = base64urlDecode(encoded);
console.log(decoded); // Original Uint8Array

API Integration

import { stringToBase64url } from "@phantom/base64url";

// Safe for URL parameters
const userData = JSON.stringify({ userId: 123, action: "login" });
const safeParam = stringToBase64url(userData);

// Use in URL without encoding issues
const apiUrl = `https://api.example.com/auth?data=${safeParam}`;

License

MIT