visionary-base64url

A lightweight, zero-dependency base64url converter for Node.js, web browsers, and worker environments.

Safely encodes Unicode text, like 🎉 ＆ 汉字, into URL-safe base64.

Install

pnpm add visionary-base64url

npm install visionary-base64url

yarn add visionary-base64url

Usage

Encode text as base64url

import { encodeBase64Url } from "visionary-base64url";

const encoded = encodeBase64Url("The quick brown fox jumps over the lazy dog.");

console.log(encoded);
// VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZy4

Decode base64url-encoded string to plain text

import { decodeBase64Url } from "visionary-base64url";

const decoded = decodeBase64Url("aHR0cHM6Ly93d3cuc3BhY2V4LmNvbS92ZWhpY2xlcy9zdGFyc2hpcA");

console.log(decoded);
// https://www.spacex.com/vehicles/starship

What is base64url?

base64url is the web-safe variant of Base64 encoding. This library handles problematic characters (+, =, /) by replacing them with URL and filename-friendly alternatives, per RFC 4648.

Where is base64url used?

Use base64url for portable, URL-safe encoding of text or JSON data, making it ideal for environments where standard Base64 might break things. Safely drop it into contexts like:

• URL paths and query parameters: embed data directly in URLs
• Filesystem-friendly: safe for filenames and blob storage keys
• Shell scripts and CI pipelines: avoid quoting or escaping issues in command-line tools and automation workflows
• JWTs and web tokens: compliant with RFC 7515 (JWS compact serialization)

Error handling

• encodeBase64Url throws when input is not a string
• decodeBase64Url throws when input is not a string or not valid base64url

Reliability and testing

• Seeded fuzz testing: deterministic pseudorandom Unicode strings encode and decode back to the original text
• Unicode edge cases: tests include ZWJ emoji, astral-plane characters, combining marks, control/invisible characters, and NFC/NFD distinctions
• Runtime parity: tests verify matching behavior across Buffer and TextEncoder/TextDecoder + btoa/atob