Upload a file
  1. base64hub
  2. Docs
  3. npm package

npm Package Reference

base64hub is an ES module for Node.js 18 and later with four functions, TypeScript types and the b64 command. No dependencies.

Install

npm i base64hub        # library
npm i -g base64hub     # b64 command

The package is ESM only. Import it with import; from CommonJS use await import("base64hub"). Type definitions ship with it.

import { encode, decode, validate, dataUri, Base64Error } from "base64hub";

encode(input, options?)

Encodes bytes, or the UTF-8 bytes of a string, and returns a string. input may be a string, a Uint8Array (a Node.js Buffer is one), an ArrayBuffer or any typed array view.

OptionTypeDefaultEffect
urlbooleanfalseURL-safe alphabet (- and _).
padbooleantrueAdd = padding.
wrapnumber0Insert \n after every N characters, none at the end; 76 is MIME.
encode("Hello, hub!");                        // "SGVsbG8sIGh1YiE="
encode("Привет", { url: true, pad: false });  // "0J_RgNC40LLQtdGC"
encode("foobar", { wrap: 4 });                // "Zm9v\nYmFy"
encode(new Uint8Array([0xfb, 0xff, 0xbf]));   // "+/+/"

decode(text)

Decodes Base64 to a Uint8Array. Spaces, tabs and line breaks, a data:...;base64, prefix, missing padding and both alphabets are accepted. Anything else throws a Base64Error whose position is the 0-based index of the bad character in the cleaned input.

decode("+/+/");                                      // Uint8Array(3) [ 251, 255, 191 ]
new TextDecoder().decode(decode("SGVsbG8sIGh1YiE")); // "Hello, hub!"

try {
  decode("Zm9v!");
} catch (e) {
  if (e instanceof Base64Error) console.log(e.message, e.position);
  // invalid character '!' at position 4 4
}

Use new TextDecoder().decode(bytes) for text and Buffer.from(bytes) when another Node.js API wants a Buffer.

validate(text)

Checks text without throwing. Valid exactly when decode would succeed.

validate("SGVsbG8sIGh1YiE");
// { valid: true, variant: 'either', padded: false, bytes: 11 }
validate("Zm9v!");
// { valid: false, error: "invalid character '!' at position 4" }
FieldMeaning
validtrue or false.
variantstandard (+ or / seen), url (- or _ seen), mixed (both) or either (neither).
paddedThe cleaned length, = included, is a multiple of 4.
bytesDecoded size in bytes.
errorOnly on invalid input: the reason, the same text decode would throw.

dataUri(input, mime?)

Builds a data:<mime>;base64,<payload> string: standard alphabet, padded, never wrapped. Without mime the type is detected: PNG, JPEG, GIF, WebP, PDF and SVG by signature, text/plain;charset=utf-8 for UTF-8 text, otherwise application/octet-stream.

dataUri("Hi");                 // "data:text/plain;charset=utf-8;base64,SGk="
dataUri("a,b", "text/csv");    // "data:text/csv;base64,YSxi"

import { readFile } from "node:fs/promises";
dataUri(await readFile("logo.png")); // "data:image/png;base64,iVBORw0KGgo..."

The b64 command

npm i -g base64hub installs b64, and npx base64hub "Hello, hub!" runs it once without installing. Flags, messages and exit codes match the CLI reference. The npm build reads the whole input into memory before working on it; for very large files use the Go build.

Updated Nov 22, 2026