O que vem no pacote
O base64hub é um módulo ES com quatro funções e nenhuma dependência. Roda no Node.js 18 ou mais novo.
| Função | Retorna |
|---|---|
encode(bytesOrString, { url, pad, wrap }) | texto Base64; strings são convertidas para UTF-8 antes |
decode(string) | um Uint8Array; lança erro com entrada inválida |
validate(string) | { valid, variant, padded, bytes }, ou { valid: false, error } |
dataUri(bytes, mime?) | uma URI data:; o tipo MIME é detectado quando você não o informa |
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="
O decode aceita o que as pessoas colam na prática: quebras de linha, espaços, preenchimento = ausente, um prefixo data:...;base64, e qualquer um dos dois alfabetos. Ele recusa todo o resto, como um ! perdido, um = no meio ou um tamanho que não pode ser Base64.
O comando b64 pelo npm
A instalação global acrescenta o comando b64, a mesma ferramenta da CLI nativa, com as mesmas flags e códigos de saída:
$ npm i -g base64hub
$ b64 "Hello, hub!"
SGVsbG8sIGh1YiE=
$ b64 -d SGVsbG8sIGh1YiE=
Hello, hub!
A versão do npm lê toda a entrada para a memória antes de processá-la. Para arquivos de vários gigabytes, use a versão em Go, que trabalha em fluxo. A documentação do npm lista todas as opções.
base64hub vs Buffer, btoa e atob
O Node.js já tem Base64 embutido, e para dados confiáveis ele basta. As diferenças aparecem com entradas que você não gerou. Estas linhas foram executadas no 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 | |
|---|---|---|---|
| Texto Unicode | sim | só Latin-1 | sim, como UTF-8 |
| Alfabeto URL-safe | codificação "base64url" | não | { url: true }, e aceito ao decodificar |
| Caracteres inválidos | pulados em silêncio | erro | erro com a posição |
| Validação | não | não | validate() |
URIs data: | não | não | dataUri(), e removido ao decodificar |
Os runtimes mais novos também trazem o Uint8Array.prototype.toBase64(); este guia mostra onde ele funciona. Para mais trechos de Node.js sem nenhum pacote, veja Base64 no Node.js.
Por que zero dependências importa aqui
Uma função auxiliar de Base64 fica no caminho de tokens, chaves e uploads de arquivos, o que a torna um péssimo lugar para uma árvore longa de dependências. O pacote usa só os módulos nativos do Node.js, o núcleo Base64 tem cerca de cem linhas, e os testes rodam os mesmos vetores de teste compartilhados que a CLI, o pacote Python e a API também passam.
Perguntas frequentes
Como instalar uma CLI Base64 pelo npm?
npm i -g base64hub instala o comando b64 globalmente. Para testar uma vez sem instalar, rode npx base64hub "Hello, hub!".
O pacote base64hub funciona com require()?
É um módulo ES, então carregue com import { encode } from "base64hub". Num arquivo CommonJS, use um await import("base64hub") dinâmico.
Por que usar um pacote se o Node.js já tem o Buffer?
O Buffer.from(text, "base64") pula os caracteres que não entende, então uma entrada danificada vira bytes errados sem nenhum erro. O decode() do base64hub rejeita essa entrada e informa a posição, e o validate() diz o alfabeto e o tamanho antes de você decodificar.
Como codificar um arquivo em Base64 no Node.js com o base64hub?
Leia os bytes e passe para a função: encode(await readFile("logo.png")), com readFile vindo de node:fs/promises. Para uma string data:image/png;base64,… pronta, chame dataUri() com os mesmos bytes.