atob for Node.js

2.1.2 · maintenance · verified Wed Apr 22

The `atob` package provides a Node.js implementation of the browser's `atob` (ASCII to Binary) function, which is used for decoding Base64-encoded strings. As of April 2026, the current stable version is 2.1.2, with the last significant update in 2018 (v2.1.0). Its release cadence appears to be very slow or effectively ceased, suggesting it's in a maintenance or stable state rather than active development. The primary differentiator of this package is its use of Node.js's native `Buffer` API to emulate the browser's exact functionality, allowing developers to decode Base64 strings in a server-side environment with behavior consistent with web browsers. A key consideration, explicitly noted by the library, is that it handles Unicode data incorrectly, mirroring the behavior of the browser's native `atob` function, which is designed for ASCII data. For proper Unicode and binary support, the README suggests alternative libraries like `unibabel.js`.

Common errors

```
SyntaxError: Named export 'atob' not found. The requested module 'atob' does not provide an export named 'atob'
```
cause Attempting to use ES module `import { atob } from 'atob'` syntax with a CommonJS-only package.

fix Change the import statement to CommonJS `const atob = require('atob');`.
```
atob is not defined
```
cause Running code in an environment (e.g., older Node.js or certain browser contexts) where global `atob` is not available and the package was not correctly imported or polyfilled.

fix Ensure the package is correctly imported via `const atob = require('atob');` at the top of your Node.js file.
```
Error: Invalid character (or something similar related to encoding failure)
```
cause Attempting to decode a Base64 string that contains non-ASCII or malformed characters, triggering the library's limitation on Unicode handling.

fix Verify the input Base64 string for correctness. If you are decoding Base64 with Unicode content, switch to Node.js's native Buffer API (e.g., `Buffer.from(base64String, 'base64').toString('utf8')`) which handles various encodings more robustly.

Warnings

gotcha The library explicitly states that Unicode may be handled incorrectly, mirroring the browser's native atob function which is designed for ASCII data. This can lead to corrupted output when decoding Base64 strings that contain non-ASCII characters.
Fix: For robust handling of Unicode and binary data, especially when dealing with UTF-8 encoded Base64, consider using Node.js's built-in Buffer API (`Buffer.from(base64String, 'base64').toString('utf8')`) or a more modern library designed for comprehensive string encoding/decoding like 'unibabel.js' if browser compatibility is also a concern.
gotcha This package is distributed as a CommonJS module only, which can cause issues or require specific configurations in modern Node.js projects that primarily use ES Modules (ESM). Direct `import` statements will not work without transpilation or specific Node.js loader setups.
Fix: Use `const atob = require('atob');` for module import. If you need ESM compatibility, consider alternative Base64 decoding methods like Node.js `Buffer.from()` or a different library that provides ESM exports.
gotcha The package has not seen significant updates since 2018 (v2.1.0), indicating it is in a maintenance mode. While it may still be functional, it might not receive updates for new Node.js versions, security patches, or bug fixes.
Fix: Evaluate whether the limited maintenance aligns with your project's needs. For critical applications, consider native Node.js Buffer methods or more actively maintained encoding libraries.

Install

npm install atob npm
yarn add atob yarn
pnpm add atob pnpm

Imports

atob
wrong:
```
import { atob } from 'atob';
```
correct:
```
const atob = require('atob');
```
This package is CommonJS only. For modern Node.js or browser environments, consider alternatives that offer ESM support or native APIs like `Buffer.from(str, 'base64').toString()`.

Quickstart

Demonstrates basic Base64 decoding of ASCII strings and highlights potential Unicode handling issues, showing how to import and use the `atob` function.

(function () {
  "use strict";

  // Import the atob function for decoding Base64 strings.
  // This package emulates the browser's atob behavior in Node.js.
  var atob = require('atob');

  // A simple Base64-encoded string representing "Hello, World!"
  var b64Ascii = "SGVsbG8sIFdvcmxkIQ==";
  var binAscii = atob(b64Ascii);
  console.log("Decoded ASCII:", binAscii); // Expected: "Hello, World!"

  // A Base64-encoded string that might contain non-ASCII characters (e.g., "你好")
  // Note: This package, like browser atob, may not handle Unicode correctly.
  // The actual encoding here assumes UTF-8 encoded bytes were Base64-encoded.
  var b64UnicodeExample = "5L2g5aW9"; // This is Base64 for '你好' (UTF-8 bytes)
  var binUnicodeAttempt = atob(b64UnicodeExample);
  console.log("Decoded Unicode (may be incorrect):", binUnicodeAttempt);
  // For correct Unicode, one would typically use Node's Buffer:
  // console.log("Correct Unicode (via Buffer):", Buffer.from(b64UnicodeExample, 'base64').toString('utf8'));

  // Another common use case: decoding URLs that might contain Base64 parameters
  // Assuming a fragment like 'data:text/plain;base64,VGhpcyBpcyBhIHRlc3Q='
  var urlEncodedB64 = "VGhpcyBpcyBhIHRlc3Q=";
  var decodedUrlContent = atob(urlEncodedB64);
  console.log("Decoded URL part:", decodedUrlContent);

  console.log("\nNote: atob is primarily for ASCII. For robust Unicode, use Buffer.from(b64, 'base64').toString('utf8').");
}());

view raw JSON →