Skip to main content

@hexagon/base64

Probably the only JavaScript base64 library you’ll ever need.

@hexagon/base64

Encode, decode and validate base64 and base64url to string or arraybuffer, and back. Works in Node, Deno or browser.

Node.js CI Deno CI npm version NPM Downloads jsdelivr Codacy Badge MIT License

  • Supports regular base64, as well as base64url
  • Convert to/from string or arraybuffer
  • Validate / identify base64 and base64url
  • Works in Node.js >=4.0 (both require and import).
  • Works in Deno >=1.16.
  • Works in browsers as standalone, UMD or ES-module.
  • Includes TypeScript typings.

Installation

Node.js

npm install @hexagon/base64 --save

JavaScript

// ESM Import ...
import base64 from "@hexagon/base64";

// ... or CommonJS Require
const base64 = require("@hexagon/base64");

TypeScript

Note that only default export is available in Node.js TypeScript, as the commonjs module is used internally.

import base64 from "@hexagon/base64";

// ...

Deno

JavaScript

import base64 from "https://cdn.jsdelivr.net/gh/hexagon/base64@1/src/base64.js";

// ...

TypeScript

import { base64 } from "https://cdn.jsdelivr.net/gh/hexagon/base64@1/src/base64.js";

// ...

Browser

Manual

  • Download latest zipball
  • Unpack
  • Grab base64.min.js (UMD and standalone) or base64.min.mjs (ES-module) from the dist/ folder

CDN

To use as a UMD-module (stand alone, RequireJS etc.)

<script src="https://cdn.jsdelivr.net/npm/@hexagon/base64@1/dist/base64.min.js"></script>

To use as a ES-module

<script type="module">
    import base64 from "https://cdn.jsdelivr.net/npm/@hexagon/base64@1/dist/base64.min.mjs";

    // ... see usage section ...
</script>

Documentation

Full documentation available at hexagon.github.io/base64.

Examples

Assuming you have imported base64 as described under ‘Installation’.

// Encode string as regular base64
const example1enc = base64.fromString("Hellö Wörld, how are you doing today?!");
console.log(example1enc);
// > SGVsbMO2IFfDtnJsZCwgaG93IGFyZSB5b3UgZG9pbmcgdG9kYXk/IQ==

// Decode string as regular base64
const example1dec = base64.toString("SGVsbMO2IFfDtnJsZCwgaG93IGFyZSB5b3UgZG9pbmcgdG9kYXk/IQ==");
console.log(example1dec);
// > Hellö Wörld, how are you doing today?!

// Encode string as base64url (setting the second parameter to true gives base64url)
const example2enc = base64.fromString("Hellö Wörld, how are you doing today?!", true);
console.log(example2enc);
// > SGVsbMO2IFfDtnJsZCwgaG93IGFyZSB5b3UgZG9pbmcgdG9kYXk_IQ

// Decode string as base64url (setting the second parameter to true takes base64url)
const example2dec = base64.toString("SGVsbMO2IFfDtnJsZCwgaG93IGFyZSB5b3UgZG9pbmcgdG9kYXk_IQ", true);
console.log(example2dec);
// > Hellö Wörld, how are you doing today?!

// Check if string is base64url (setting the second parameter to true validates base64url)
const example3valid = base64.validate("SGVsbMO2IFfDtnJsZCwgaG93IGFyZSB5b3UgZG9pbmcgdG9kYXk_IQ", true);
console.log(example3valid);
// > true

// Check if string is base64
const example4valid = base64.validate("SGVsbMO2IFfDtnJsZCwgaG93IGFyZSB5b3UgZG9pbmcgdG9kYXk_IQ");
console.log(example4valid);
// > false

// Check if string is base64
const example5valid = base64.validate("SGVsbMO2IFfDtnJsZCwgaG93IGFyZSB5b3UgZG9pbmcgdG9kYXk/IQ==");
console.log(example5valid);
// > true

Full API

The library encodes and decodes base64/base64url to and from ArrayBuffers

  • fromArrayBuffer(buffer, urlMode) - Encodes ArrayBuffer into base64 or base64url if urlMode (optional) is true

  • toArrayBuffer(str, urlMode) - Decodes base64url string (or base64url string if urlMode is true) to ArrayBuffer

  • fromString(str) - Encodes String into base64 string

  • toString(str) - Decodes base64 string to String

  • validate(str, urlMode) - Returns true if String str is valid base64/base64 dependending on urlMode

Contributing

See Contribution Guide

Contributors

The underlying code is loosely based on github.com/niklasvh/base64-arraybuffer

License

MIT