パッケージの中身
base64hub は 4 つの関数を持つ ES モジュールで、依存関係はありません。Node.js 18 以降で動きます。
| 関数 | 戻り値 |
|---|---|
encode(bytesOrString, { url, pad, wrap }) | Base64 のテキスト。文字列は先に UTF-8 に変換される |
decode(string) | Uint8Array。無効な入力では例外を投げる |
validate(string) | { valid, variant, padded, bytes } または { valid: false, error } |
dataUri(bytes, mime?) | data: URI。MIME タイプを省略すると自動判定 |
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 は、実際によく貼り付けられるものを受け付けます。改行、空白、= パディングの欠落、data:...;base64, 接頭辞、どちらのアルファベットもです。それ以外、たとえば紛れ込んだ !、途中の =、Base64 としてありえない長さは拒否します。
npm で入る b64 コマンド
グローバルにインストールすると b64 コマンドが追加されます。ネイティブ版の CLI と同じツールで、フラグも終了コードも同じです。
$ npm i -g base64hub
$ b64 "Hello, hub!"
SGVsbG8sIGh1YiE=
$ b64 -d SGVsbG8sIGh1YiE=
Hello, hub!
npm 版は入力をすべてメモリに読み込んでから処理します。数 GB のファイルには、ストリーム処理する Go 版を使ってください。すべてのオプションは npm パッケージのドキュメント にあります。
base64hub と Buffer、btoa、atob の違い
Node.js には Base64 が最初から組み込まれていて、信頼できるデータならそれで十分です。差が出るのは、自分で作ったのではない入力を扱うときです。以下は 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 テキスト | 可 | Latin-1 のみ | 可(UTF-8 として) |
| URLセーフなアルファベット | "base64url" エンコーディング | 不可 | { url: true }。デコード時も受け付ける |
| 無効な文字 | 黙って読み飛ばす | エラー | 位置付きのエラー |
| 検証 | なし | なし | validate() |
data: URI | なし | なし | dataUri()。デコード時は取り除く |
新しいランタイムには Uint8Array.prototype.toBase64() もあります。どこで使えるかは こちらのガイド で説明しています。パッケージを使わない Node.js のコード例は Node.js での Base64 をご覧ください。
ここで依存関係ゼロが大事な理由
Base64 のヘルパーはトークン、鍵、ファイルアップロードの通り道にあるので、長い依存関係ツリーを抱えるには向かない場所です。このパッケージは Node.js の組み込み機能だけを使い、Base64 の中核部分は 100 行ほどです。テストでは、CLI、Python パッケージ、API も通っている共通のテストベクターを実行しています。
よくある質問
npm で Base64 の CLI をインストールするには?
npm i -g base64hub で b64 コマンドがグローバルにインストールされます。インストールせずに一度だけ試すなら、npx base64hub "Hello, hub!" を実行してください。
base64hub パッケージは require() で読み込めますか?
ES モジュールなので、import { encode } from "base64hub" で読み込みます。CommonJS のファイルでは、動的な await import("base64hub") を使ってください。
Node.js には Buffer があるのに、なぜパッケージを使うのですか?
Buffer.from(text, "base64") は理解できない文字を読み飛ばすので、壊れた入力がエラーにならず、間違ったバイト列になります。base64hub の decode() はそうした入力を拒否して位置を報告し、validate() はデコード前にアルファベットとサイズを教えてくれます。
base64hub を使って Node.js でファイルを Base64 エンコードするには?
バイト列を読み込んで渡します。node:fs/promises の readFile を使って encode(await readFile("logo.png")) とします。そのまま使える data:image/png;base64,… 形式の文字列が欲しければ、同じバイト列で dataUri() を呼びます。