js-base64

js-base64 is a dependency-free Base64 transcoder for JavaScript and TypeScript that works consistently across browsers, Node.js, Deno, and Bun. Unlike the built-in btoa/atob functions, which only handle Latin1 binary strings and throw on non-ASCII text, js-base64 correctly encodes and decodes arbitrary Unicode strings (including emoji and multi-byte UTF-8 text) by internally using TextEncoder/TextDecoder where available and falling back to hand-written polyfills where they are not.

The library ships as CommonJS, an ES module, and a UMD/browser global, with first-class TypeScript declaration files for both, so it drops into virtually any JavaScript environment without configuration. It also supports the URL-safe Base64 variant (-/_ instead of +//, no padding) out of the box, which is commonly needed for JWTs, URL query parameters, and filenames — one of the most common reasons projects reach for a dedicated Base64 library instead of the platform built-ins.

What You Get

• Base64.encode/Base64.decode functions that correctly round-trip full Unicode strings, including multi-byte UTF-8 and emoji
• URL-safe Base64 encoding/decoding (-/_ alphabet, optional padding removal) for use in JWTs, URLs, and filenames
• Drop-in polyfills for native btoa/atob behavior where the environment lacks them
• Distribution as CommonJS (base64.js), ES module (base64.mjs), and UMD/browser global, each with matching TypeScript declarations
• Zero runtime dependencies and a small, auditable single-file implementation

Common Use Cases

• Encoding/decoding JWT header and payload segments in auth middleware
• Safely embedding binary data (images, files) as Base64 strings in JSON payloads or data URIs
• URL-safe encoding of identifiers or tokens passed as query parameters or path segments
• Cross-runtime utilities that need identical Base64 behavior in both browser and Node.js/Deno code
• Encoding Unicode strings for storage or transport where native btoa would throw on non-Latin1 characters

Under The Hood

Architecture The library is authored as a single TypeScript source file (base64.ts, ~300 lines) that is compiled to three distribution targets: a CommonJS build (base64.js), an ES module (base64.mjs), and matching .d.ts/.d.mts type declarations, all wired together via package.json exports conditions so bundlers and runtimes resolve the right format automatically. Internally, encode/decode operations branch on feature detection: where TextEncoder/TextDecoder are available (all modern browsers, Node, Deno, Bun) they’re used directly for UTF-8 conversion; where they aren’t, hand-written btoaPolyfill/atobPolyfill functions perform the same conversion byte-by-byte using character-code arithmetic.

Tech Stack Written in TypeScript with zero runtime dependencies, built via a Makefile (not a JS bundler) that invokes tsc to emit the CJS/ESM/type-declaration outputs, and tested with Mocha. The test/ directory includes targeted suites for BOM handling, large-input performance, atob compatibility, and ES5 vs ES6 code paths.

Code Quality Test coverage spans edge cases specific to Base64/Unicode correctness — byte-order-mark handling (bom.js), large payloads (large.js), ES5 fallback behavior (es5.js) — rather than just happy-path encode/decode, reflecting the project’s long history of fixing subtle cross-environment bugs. The single-file implementation keeps the surface area small enough to audit fully, and inline JSDoc comments document each exported function’s parameters and return values.

API Design The API centers on a Base64 namespace object (Base64.encode, Base64.decode, Base64.encodeURI, etc.) plus equivalent named exports (encode, decode) for consumers who prefer tree-shakeable imports over the namespace object — both documented side by side in the README so migrating between styles is a one-line change. noConflict() is provided for browser-global usage to avoid clobbering an existing Base64 global, a detail that shows attention to real-world script-tag consumption alongside modern module usage.