{"id":13358,"library":"isomorphic-base64","title":"Isomorphic Base64","description":"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.","status":"maintenance","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/ksheedlo/isomorphic-base64","tags":["javascript","isomorphic","base64","browserify","ascii"],"install":[{"cmd":"npm install isomorphic-base64","lang":"bash","label":"npm"},{"cmd":"yarn add isomorphic-base64","lang":"bash","label":"yarn"},{"cmd":"pnpm add isomorphic-base64","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import base64 from 'isomorphic-base64'; // Works, but direct destructuring is more common for this API","symbol":"atob, btoa","correct":"import { atob, btoa } from 'isomorphic-base64';"},{"note":"Standard CommonJS requiring syntax.","symbol":"atob, btoa (CJS)","correct":"const { atob, btoa } = require('isomorphic-base64');"},{"note":"Imports the entire exports object, then accesses properties. This is also valid for ESM via `import * as base64 from 'isomorphic-base64';`","symbol":"Full module (CJS)","correct":"const base64 = require('isomorphic-base64');\nconst encoded = base64.btoa('hello');"}],"quickstart":{"code":"import { atob, btoa } from 'isomorphic-base64';\n\n// 1. Basic ASCII/Latin-1 encoding and decoding\nconst originalAscii = 'Hello, World!';\nconst encodedAscii = btoa(originalAscii);\nconsole.log('Encoded ASCII:', encodedAscii); // SGVsbG8sIFdvcmxkIQ==\nconst decodedAscii = atob(encodedAscii);\nconsole.log('Decoded ASCII:', decodedAscii); // Hello, World!\n\n// 2. Handling Unicode characters (common pitfall with btoa/atob)\n// btoa/atob only work correctly with 'binary strings' (where each char is a byte).\n// For proper Unicode handling, you must encode/decode to UTF-8 bytes first.\n\nconst originalUnicode = 'Hello, 世界! 👋';\n\ntry {\n  btoa(originalUnicode); // This will throw an error in most environments if characters are outside Latin-1\n} catch (error) {\n  console.error('\\nError with direct Unicode encoding:', error.message); \n  console.error('This is a common limitation of btoa/atob for multi-byte characters.');\n}\n\n// Correct way to encode/decode Unicode with btoa/atob (requires intermediate UTF-8 step)\n// Using TextEncoder/TextDecoder (modern browser/Node.js)\nconst encoder = new TextEncoder();\nconst decoder = new TextDecoder();\n\nconst utf8Bytes = encoder.encode(originalUnicode);\nconst latin1String = String.fromCharCode(...utf8Bytes); // Convert Uint8Array to 'binary string'\nconst encodedUnicode = btoa(latin1String);\nconsole.log('\\nEncoded Unicode (correctly):', encodedUnicode);\n\nconst decodedLatin1 = atob(encodedUnicode);\nconst decodedUtf8Bytes = Uint8Array.from(decodedLatin1, char => char.charCodeAt(0));\nconst decodedUnicode = decoder.decode(decodedUtf8Bytes);\nconsole.log('Decoded Unicode (correctly):', decodedUnicode); // Hello, 世界! 👋\n\n// Fallback for older environments (Node.js < 11 or very old browsers) for Unicode:\n// encodeURIComponent and unescape (though unescape is deprecated)\nconst oldWayEncoded = btoa(unescape(encodeURIComponent(originalUnicode)));\nconsole.log('Encoded Unicode (old way):', oldWayEncoded);\nconst oldWayDecoded = decodeURIComponent(escape(atob(oldWayEncoded)));\nconsole.log('Decoded Unicode (old way):', oldWayDecoded);\n\n// This quickstart demonstrates how to use the isomorphic-base64 library for basic ASCII \n// Base64 operations and crucially highlights the common pitfall with Unicode characters, \n// providing modern and older workarounds for proper handling. It covers both encoding and decoding aspects.\n","lang":"javascript","description":"Demonstrates basic Base64 encoding/decoding for ASCII strings and provides crucial workarounds for correctly handling Unicode characters, a common limitation of `atob`/`btoa`."},"warnings":[{"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`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"This 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).","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"`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.","error":"Failed to execute 'btoa' on 'Window': The string to be encoded contains characters outside of the Latin1 range."},{"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.","cause":"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.","error":"TypeError: Cannot destructure property 'atob' of 'require(...)' as it is undefined."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}