{"id":12915,"library":"btoa-lite","title":"btoa-lite","description":"btoa-lite provides a lightweight, isomorphic `btoa` (Base64 encoding) implementation for both Node.js and browser environments. Its primary differentiator is its approach to environment-specific code loading, utilizing `package.json`'s `main` and `browser` fields to avoid bundling Browserify's potentially large `Buffer` shim into browser builds. This ensures minimal bundle sizes for browser targets while providing a functional Base64 encoder in Node.js using its native `Buffer` API. As of version 1.0.0, it is a stable, mature package, likely in a maintenance state given its last publish in 2016, with a focus on simplicity over frequent feature updates. It aims to be the smallest and simplest means for `btoa` functionality across environments.","status":"maintenance","version":"1.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/hughsk/btoa-lite","tags":["javascript","btoa","base64","isomorphic","browser","node","shared"],"install":[{"cmd":"npm install btoa-lite","lang":"bash","label":"npm"},{"cmd":"yarn add btoa-lite","lang":"bash","label":"yarn"},{"cmd":"pnpm add btoa-lite","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The package exports the btoa function directly as its default export in CommonJS.","wrong":"const { btoa } = require('btoa-lite');","symbol":"btoa","correct":"const btoa = require('btoa-lite');"},{"note":"For ESM projects, use a default import. This assumes your bundler correctly handles CJS interop.","wrong":"import { btoa } from 'btoa-lite';","symbol":"btoa","correct":"import btoa from 'btoa-lite';"},{"note":"TypeScript users will likely need to provide a custom declaration file (e.g., `declare module 'btoa-lite';` or `declare function btoaLite(str: string): string; export = btoaLite;`) as `@types/btoa-lite` does not exist.","wrong":"import type { btoa } from 'btoa-lite';","symbol":"btoa (Type Definition)","correct":"// No official type definitions for 'btoa-lite'."}],"quickstart":{"code":"const btoa = require('btoa-lite');\n\nconst inputString = 'Hello, world! 👋 This is a test string with some Unicode.';\n\n// btoa can only handle Latin-1 characters directly. Unicode must be pre-encoded.\n// For arbitrary Unicode, a common pattern is to encode to UTF-8 first.\nfunction utf8_to_b64(str) {\n  return btoa(encodeURIComponent(str).replace(/%([0-9A-F]{2})/g,\n    function toSolidBytes(match, p1) {\n      return String.fromCharCode('0x' + p1);\n    }));\n}\n\nfunction b64_to_utf8(str) {\n  return decodeURIComponent(atob(str).split('').map(function(c) {\n    return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2);\n  }).join(''));\n}\n\n// Example with Latin-1 compatible string\nconst latin1Input = 'Hello, world!';\nconst encodedLatin1 = btoa(latin1Input);\nconsole.log(`Original (Latin-1): ${latin1Input}`);\nconsole.log(`Encoded (Latin-1): ${encodedLatin1}`);\n\n// Example with arbitrary Unicode string\nconst encodedUnicode = utf8_to_b64(inputString);\nconsole.log(`\\nOriginal (Unicode): ${inputString}`);\nconsole.log(`Encoded (Unicode, via UTF-8): ${encodedUnicode}`);\n\nconst decodedUnicode = b64_to_utf8(encodedUnicode);\nconsole.log(`Decoded (Unicode, via UTF-8): ${decodedUnicode}`);\n\n// Verify compatibility across environments (Node.js Buffer vs. browser btoa)\nif (typeof Buffer !== 'undefined') {\n  const nodeBufferEncoded = Buffer.from(latin1Input).toString('base64');\n  console.log(`\\nNode.js Buffer encoded: ${nodeBufferEncoded}`);\n  console.log(`Matches btoa-lite for Latin-1: ${nodeBufferEncoded === encodedLatin1}`);\n}\n","lang":"javascript","description":"Demonstrates Base64 encoding for both Latin-1 compatible and arbitrary Unicode strings using `btoa-lite`, including a common pattern for UTF-8 pre-encoding."},"warnings":[{"fix":"For arbitrary Unicode strings, first encode the string to UTF-8, then encode the resulting byte string with `btoa`. The `quickstart` example provides a utility function `utf8_to_b64` for this purpose.","message":"`btoa` (and thus `btoa-lite`) fundamentally expects strings where each character represents a single byte (like Latin-1). It does not natively handle arbitrary Unicode characters (e.g., emojis, many international characters) without prior UTF-8 encoding. Attempting to encode such strings directly will result in errors or incorrect output.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For applications requiring modern Node.js APIs, consider alternatives that use `Buffer.from(string)` or ensure your environment tolerates the deprecation warning. `btoa-lite` itself is a low-level utility and does not provide an option to switch implementations.","message":"The internal Node.js implementation within `btoa-lite` uses the `new Buffer(string)` constructor, which has been deprecated since Node.js 6.0.0 and emits a `DeprecationWarning`. While it still functions in many environments, it is considered a legacy API.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"In ESM contexts, always use the default import syntax `import btoa from 'btoa-lite';`. If issues persist, consider using `require()` within an `import` wrapper or a dynamic `import()` for more control.","message":"`btoa-lite` is a CommonJS (CJS) module. While modern bundlers and Node.js versions often handle CJS modules in ESM contexts, direct `import` statements might require specific configuration or might lead to issues if not correctly handled, e.g., using `import btoa from 'btoa-lite';` instead of named imports.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Evaluate if an actively maintained alternative like `js-base64` or a custom implementation using `Buffer.from().toString('base64')` (for Node.js) and `window.btoa()` (for browsers) might be more suitable for long-term projects.","message":"The package was last published in 2016 and appears to be in a maintenance-only state. This means it may not receive updates for new Node.js versions, security vulnerabilities (though minimal for this type of utility), or compatibility with cutting-edge bundler features.","severity":"gotcha","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":"Pre-encode the Unicode string into a UTF-8 byte string before passing it to `btoa-lite`. Refer to the `utf8_to_b64` function in the quickstart example.","cause":"Attempting to encode a string containing Unicode characters (e.g., non-ASCII, emojis, characters outside U+00FF) directly with `btoa-lite`.","error":"TypeError: The string to be encoded contains characters outside of the Latin1 range."},{"fix":"When using `require('btoa-lite')`, the module itself returns the `btoa` function directly. Use `const btoa = require('btoa-lite');` instead of `const { btoa } = require('btoa-lite');`.","cause":"Incorrectly trying to access `btoa-lite.btoa` after requiring the module, assuming it's an object with a named export.","error":"TypeError: btoa-lite is not a function"},{"fix":"Ensure `btoa-lite` is correctly bundled for your target environment. If trying to use `Buffer` directly in a browser, ensure a `Buffer` shim (like the one provided by Browserify) is present.","cause":"This error is unlikely to occur with `btoa-lite` itself due to its environment detection. However, if using a similar logic manually or if `btoa-lite`'s browser field is somehow ignored, it indicates that Node.js's `Buffer` global is not available in the current environment (e.g., a browser without a `Buffer` shim).","error":"ReferenceError: Buffer is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}