Registry / serialization / isomorphic-base64

isomorphic-base64

library1.0.2jsnpmunverified

isomorphic-base64 is a compact, zero-dependency utility that provides consistent Base64 encoding and decoding functionality across both Node.js and browser environments. It exports `atob` and `btoa` functions, mirroring the browser's global Web API for Base64 operations. Currently at version 1.0.2, the package was last published over a decade ago (May 2015), indicating a highly stable and mature codebase that has seen no significant breaking changes or feature additions, operating on a maintenance-only release cadence. Its key differentiator is providing a reliable polyfill or abstraction layer, ensuring that applications can perform Base64 transformations uniformly without needing to conditionally implement Node.js's `Buffer` API or rely on the global `window.atob`/`window.btoa` in browsers. It primarily handles ASCII/Latin-1 strings, a common limitation of the native `atob`/`btoa` functions.

serialization

npm install isomorphic-base64

github ↗package ↗

INSTALL

IMPORT

SIG · ISOMORPHIC-BASE64

isomorphic-base64

serializationjavascriptv1.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

atob, btoa

✓ import { atob, btoa } from 'isomorphic-base64';

✗ import base64 from 'isomorphic-base64'; // Works, but direct destructuring is more common for this API

For ESM environments, named imports are the canonical way to access the functions. This package is a CommonJS module, but Node.js allows named imports for CJS exports.

atob, btoa (CJS)

✓ const { atob, btoa } = require('isomorphic-base64');

Standard CommonJS requiring syntax.

Full module (CJS)

✓ const base64 = require('isomorphic-base64'); const encoded = base64.btoa('hello');

Imports the entire exports object, then accesses properties. This is also valid for ESM via `import * as base64 from 'isomorphic-base64';`

Demonstrates basic Base64 encoding/decoding for ASCII strings and provides crucial workarounds for correctly handling Unicode characters, a common limitation of `atob`/`btoa`.

import { atob, btoa } from 'isomorphic-base64'; // 1. Basic ASCII/Latin-1 encoding and decoding const originalAscii = 'Hello, World!'; const encodedAscii = btoa(originalAscii); console.log('Encoded ASCII:', encodedAscii); // SGVsbG8sIFdvcmxkIQ== const decodedAscii = atob(encodedAscii); console.log('Decoded ASCII:', decodedAscii); // Hello, World! // 2. Handling Unicode characters (common pitfall with btoa/atob) // btoa/atob only work correctly with 'binary strings' (where each char is a byte). // For proper Unicode handling, you must encode/decode to UTF-8 bytes first. const originalUnicode = 'Hello, 世界! 👋'; try { btoa(originalUnicode); // This will throw an error in most environments if characters are outside Latin-1 } catch (error) { console.error('\nError with direct Unicode encoding:', error.message); console.error('This is a common limitation of btoa/atob for multi-byte characters.'); } // Correct way to encode/decode Unicode with btoa/atob (requires intermediate UTF-8 step) // Using TextEncoder/TextDecoder (modern browser/Node.js) const encoder = new TextEncoder(); const decoder = new TextDecoder(); const utf8Bytes = encoder.encode(originalUnicode); const latin1String = String.fromCharCode(...utf8Bytes); // Convert Uint8Array to 'binary string' const encodedUnicode = btoa(latin1String); console.log('\nEncoded Unicode (correctly):', encodedUnicode); const decodedLatin1 = atob(encodedUnicode); const decodedUtf8Bytes = Uint8Array.from(decodedLatin1, char => char.charCodeAt(0)); const decodedUnicode = decoder.decode(decodedUtf8Bytes); console.log('Decoded Unicode (correctly):', decodedUnicode); // Hello, 世界! 👋 // Fallback for older environments (Node.js < 11 or very old browsers) for Unicode: // encodeURIComponent and unescape (though unescape is deprecated) const oldWayEncoded = btoa(unescape(encodeURIComponent(originalUnicode))); console.log('Encoded Unicode (old way):', oldWayEncoded); const oldWayDecoded = decodeURIComponent(escape(atob(oldWayEncoded))); console.log('Decoded Unicode (old way):', oldWayDecoded); // This quickstart demonstrates how to use the isomorphic-base64 library for basic ASCII // Base64 operations and crucially highlights the common pitfall with Unicode characters, // providing modern and older workarounds for proper handling. It covers both encoding and decoding aspects.

Debug

Known issues

gotchaThe native `atob` and `btoa` functions (and thus this polyfill) are designed for 'binary strings' where each character represents a single byte (e.g., Latin-1 or ASCII). Directly encoding strings containing multi-byte Unicode characters (like emojis or non-Latin scripts) will result in an error or incorrect output.

fix

Before encoding Unicode strings, convert them to a byte array (e.g., UTF-8) and then to a Latin-1 compatible string using `TextEncoder` and `String.fromCharCode` for `btoa`. For decoding, reverse the process using `atob`, `Uint8Array.from`, and `TextDecoder`. See quickstart for example. Older browsers might need `encodeURIComponent`/`escape`/`unescape`.

affects: >=1.0.0

gotchaThis package was last updated over 10 years ago. While stable for its core functionality, it does not incorporate newer JavaScript features, Node.js Buffer optimizations, or browser Web API additions (like `TextEncoder`/`TextDecoder` for direct `Uint8Array` to Base64 conversion).

fix

For new projects, consider native Node.js `Buffer` API (`Buffer.from(str).toString('base64')`), modern browser `btoa`/`atob` with careful Unicode handling, or newer isomorphic Base64 libraries that might leverage `TextEncoder`/`TextDecoder` more directly for robust Unicode support.

affects: >=1.0.0

deprecatedThe global `atob` and `btoa` functions in Node.js were briefly marked as deprecated in TypeScript definitions (v4.x to v5.x) due to their Latin-1 limitation, although they were not formally deprecated in the Node.js runtime itself. This caused confusion, as `isomorphic-base64` provides these functions.

fix

For Node.js, directly using `Buffer.from(str).toString('base64')` and `Buffer.from(base64Str, 'base64').toString()` is generally preferred for byte-safe Base64 operations, especially with Unicode. This package still provides `atob`/`btoa` for browser compatibility, but be mindful of their limitations.

affects: >=1.0.0

Errors

Common errors & fixes

Failed to execute 'btoa' on 'Window': The string to be encoded contains characters outside of the Latin1 range.

`btoa` was called with a string containing characters that cannot be represented in a single byte (i.e., outside of the Latin-1 character set), such as multi-byte UTF-8 characters or emojis.

fix

Before calling `btoa`, encode the string to UTF-8 bytes and then convert those bytes into a 'binary string' where each character corresponds to a byte. This can be done using `TextEncoder` and `String.fromCharCode()` (or `encodeURIComponent`/`unescape` for older environments). See the quickstart example for details.

TypeError: Cannot destructure property 'atob' of 'require(...)' as it is undefined.

This error typically occurs in a pure ESM environment where `require` is not available, or when a bundler fails to correctly transpile CommonJS `require` calls into ESM imports for named exports from a CJS module.

fix

Ensure your build setup (e.g., webpack, Rollup, Parcel, Node.js with `type: 'module'`) is configured to handle CommonJS modules correctly. For pure ESM, use `import { atob, btoa } from 'isomorphic-base64';` or consider dynamically importing `import('isomorphic-base64')` if `require` is strictly unavailable and direct named CJS imports are not working.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/ksheedlo/isomorphic-base64 ↗

packagehttps://www.npmjs.com/package/isomorphic-base64 ↗