What is in the package
base64hub is an ES module with four functions and no dependencies. It runs on Node.js 18 and later.
| Function | Returns |
|---|---|
encode(bytesOrString, { url, pad, wrap }) | Base64 text; strings are encoded as UTF-8 first |
decode(string) | a Uint8Array; throws on invalid input |
validate(string) | { valid, variant, padded, bytes }, or { valid: false, error } |
dataUri(bytes, mime?) | a data: URI; the MIME type is detected when you leave it out |
npm i base64hub
import { encode, decode, validate, dataUri } from "base64hub";
encode("Hello, hub!"); // "SGVsbG8sIGh1YiE="
encode("Привет", { url: true, pad: false }); // "0J_RgNC40LLQtdGC"
new TextDecoder().decode(decode("SGVsbG8sIGh1YiE")); // "Hello, hub!"
validate("-_-_").variant; // "url"
dataUri(new TextEncoder().encode("Hi")); // "data:text/plain;charset=utf-8;base64,SGk="
decode accepts what people paste in practice: line breaks, spaces, missing = padding, a data:...;base64, prefix, and either alphabet. It refuses everything else, such as a stray !, a = in the middle or a length that cannot be Base64.
The b64 command from npm
Installing globally adds the b64 command, the same tool as the native CLI with the same flags and exit codes:
$ npm i -g base64hub
$ b64 "Hello, hub!"
SGVsbG8sIGh1YiE=
$ b64 -d SGVsbG8sIGh1YiE=
Hello, hub!
The npm build reads all input into memory before it works on it. For multi-gigabyte files use the Go build, which streams. The npm docs list every option.
base64hub vs Buffer, btoa and atob
Node.js already has Base64 built in, and for trusted data it is fine. The differences show up with input you did not produce yourself. These lines were run on Node.js 24:
Buffer.from("Zm9v!YmFy", "base64").toString(); // "foobar", the "!" is skipped silently
btoa("Привет"); // throws InvalidCharacterError (Latin-1 only)
atob("-_-_"); // throws InvalidCharacterError (no URL-safe)
Buffer | btoa / atob | base64hub | |
|---|---|---|---|
| Unicode text | yes | Latin-1 only | yes, as UTF-8 |
| URL-safe alphabet | "base64url" encoding | no | { url: true }, and accepted when decoding |
| Invalid characters | skipped silently | error | error with position |
| Validation | no | no | validate() |
data: URIs | no | no | dataUri(), and stripped when decoding |
Newer runtimes also add Uint8Array.prototype.toBase64(); this guide covers where it works. For more Node.js snippets without any package, see Base64 in Node.js.
Why zero dependencies matters here
A Base64 helper sits in the path of tokens, keys and file uploads, which makes it a poor place for a long dependency tree. The package uses only Node.js built-ins, its Base64 core is about a hundred lines, and its tests run the shared test vectors that the CLI, the Python package and the API also pass.
FAQ
How do I install a Base64 CLI with npm?
npm i -g base64hub installs the b64 command globally. To try it once without installing, run npx base64hub "Hello, hub!".
Does the base64hub package work with require()?
It is an ES module, so load it with import { encode } from "base64hub". In a CommonJS file use a dynamic await import("base64hub").
Why use a package when Node.js has Buffer?
Buffer.from(text, "base64") skips characters it does not understand, so damaged input turns into wrong bytes without an error. decode() from base64hub rejects it and reports the position, and validate() tells you the alphabet and size before you decode.
How do I Base64 encode a file in Node.js with base64hub?
Read the bytes and pass them in: encode(await readFile("logo.png")) with readFile from node:fs/promises. For a ready-made data:image/png;base64,… string, call dataUri() on the same bytes.