Registry / serialization / btoa-lite

btoa-lite

JSON →
library1.0.0jsnpmunverified

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.

serializationhttp-networking
npm install btoa-lite
github ↗package ↗
INSTALL
IMPORT
SIG · BTOA-LITE
B
btoa-lite
serializationjavascriptv1.0.0
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.

btoa
✓ const btoa = require('btoa-lite');
✗ const { btoa } = require('btoa-lite');
The package exports the btoa function directly as its default export in CommonJS.
btoa
✓ import btoa from 'btoa-lite';
✗ import { btoa } from 'btoa-lite';
For ESM projects, use a default import. This assumes your bundler correctly handles CJS interop.
btoa (Type Definition)
✓ // No official type definitions for 'btoa-lite'.
✗ import type { btoa } from 'btoa-lite';
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.

Demonstrates Base64 encoding for both Latin-1 compatible and arbitrary Unicode strings using `btoa-lite`, including a common pattern for UTF-8 pre-encoding.

const btoa = require('btoa-lite'); const inputString = 'Hello, world! 👋 This is a test string with some Unicode.'; // btoa can only handle Latin-1 characters directly. Unicode must be pre-encoded. // For arbitrary Unicode, a common pattern is to encode to UTF-8 first. function utf8_to_b64(str) { return btoa(encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, function toSolidBytes(match, p1) { return String.fromCharCode('0x' + p1); })); } function b64_to_utf8(str) { return decodeURIComponent(atob(str).split('').map(function(c) { return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2); }).join('')); } // Example with Latin-1 compatible string const latin1Input = 'Hello, world!'; const encodedLatin1 = btoa(latin1Input); console.log(`Original (Latin-1): ${latin1Input}`); console.log(`Encoded (Latin-1): ${encodedLatin1}`); // Example with arbitrary Unicode string const encodedUnicode = utf8_to_b64(inputString); console.log(`\nOriginal (Unicode): ${inputString}`); console.log(`Encoded (Unicode, via UTF-8): ${encodedUnicode}`); const decodedUnicode = b64_to_utf8(encodedUnicode); console.log(`Decoded (Unicode, via UTF-8): ${decodedUnicode}`); // Verify compatibility across environments (Node.js Buffer vs. browser btoa) if (typeof Buffer !== 'undefined') { const nodeBufferEncoded = Buffer.from(latin1Input).toString('base64'); console.log(`\nNode.js Buffer encoded: ${nodeBufferEncoded}`); console.log(`Matches btoa-lite for Latin-1: ${nodeBufferEncoded === encodedLatin1}`); }
Debug
Known issues
gotcha`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.
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.
affects: >=1.0.0
deprecatedThe 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.
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.
affects: >=1.0.0
gotcha`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.
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.
affects: >=1.0.0
gotchaThe 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.
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.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: The string to be encoded contains characters outside of the Latin1 range.
Attempting to encode a string containing Unicode characters (e.g., non-ASCII, emojis, characters outside U+00FF) directly with `btoa-lite`.
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.
TypeError: btoa-lite is not a function
Incorrectly trying to access `btoa-lite.btoa` after requiring the module, assuming it's an object with a named export.
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');`.
ReferenceError: Buffer is not defined
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).
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.
Upgrade
Version history
1.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources
githubhttps://github.com/hughsk/btoa-lite ↗
packagehttps://www.npmjs.com/package/btoa-lite ↗
btoa-lite — npm install btoa-lite · libregistry