Need to perform a typescript base64 encode or decode operation, but struggling with runtime environment differences, Unicode corruption, or weak type safety? You are in the right place.

In modern web development, converting binary data or strings to Base64 is a highly common task. Whether you are dealing with image uploads, JSON Web Tokens (JWTs), API authorization headers, or database payloads, doing this safely in TypeScript requires navigating platform quirks and leveraging compiler features.

In this comprehensive guide, we will look at how to master Base64 in TypeScript. We will cover standard platform-specific methods, explore why native browser functions crash when handling Unicode characters, build an isomorphic utility that works seamlessly in any environment, and implement custom TypeScript types to enforce compile-time type safety.

1. The Core Environments: Node.js vs. the Browser

When writing TypeScript, you must always be conscious of where your code will execute. An application written for the backend (Node.js) handles binary data and Base64 conversions completely differently than code executing in a frontend browser environment.

Encoding in Node.js: The Power of Buffer

Node.js does not have the native browser functions btoa() or atob() available by default in older runtimes. Instead, it relies on the highly optimized Buffer class, which is designed specifically to handle raw binary data.

To encode a string to Base64 in a Node.js context, you convert the string into a buffer with UTF-8 encoding, and then convert that buffer into a string using the 'base64' format:

import { Buffer } from 'node:buffer';

/**
 * Encodes a standard UTF-8 string into a Base64 string in Node.js.
 */
export function nodeEncodeBase64(input: string): string {
  return Buffer.from(input, 'utf-8').toString('base64');
}

/**
 * Decodes a Base64 string back into a UTF-8 string in Node.js.
 */
export function nodeDecodeBase64(base64Input: string): string {
  return Buffer.from(base64Input, 'base64').toString('utf-8');
}

// Usage Example:
const original = 'Hello, TypeScript! 🚀';
const encoded = nodeEncodeBase64(original);
console.log(encoded); // Output: SGVsbG8sIFR5cGVTY3JpcHQhIPCfkg==

const decoded = nodeDecodeBase64(encoded);
console.log(decoded); // Output: Hello, TypeScript! 🚀

Note: In modern Node.js setups, you should import Buffer from 'node:buffer' rather than relying on the global namespace. This makes your imports explicit and aligns with current modern Node.js conventions. Ensure you have @types/node installed in your devDependencies so TypeScript can resolve the type definitions for Buffer.

Encoding in the Browser: The Legacy of btoa and atob

In client-side environments, browsers provide two globally accessible utility functions:

• btoa(): Stands for Binary to ASCII. It takes a binary string (or string of 8-bit characters) and encodes it into Base64.
• atob(): Stands for ASCII to Binary. It takes a Base64 encoded string and decodes it back to a binary string.

Here is how you write basic Base64 encode and decode functions using these APIs:

/**
 * Basic browser-based Base64 encoding (ASCII only).
 */
export function basicBrowserEncode(input: string): string {
  return window.btoa(input);
}

/**
 * Basic browser-based Base64 decoding (ASCII only).
 */
export function basicBrowserDecode(base64Input: string): string {
  return window.atob(base64Input);
}

While this works perfectly for simple English text (ASCII), this approach has a critical, silent flaw that crashes production applications: the Unicode problem.

2. The Unicode Nightmare: Safe UTF-8 Base64 Encoding in TypeScript

If you try to use btoa() in the browser with characters outside of the Latin-1 range (characters with code points from 0 to 255), the browser will throw a nasty DOMException: The string to be encoded contains characters outside of the Latin1 range.

This means if a user enters an emoji (like 🧀 or 🚀), a non-English character (like ñ, ü, or 한), or a complex character sequence, your app will immediately crash.

Why Does This Crash Occur?

JavaScript strings are represented internally as UTF-16 code units. However, the btoa() function expects each character of the input string to represent a single byte of binary data. Because emojis and non-Latin characters require multiple bytes to represent, they break the mathematical assumptions of btoa().

The Modern Solution: TextEncoder and TextDecoder

To bypass this limitation, we must first convert our UTF-16 JavaScript string into raw UTF-8 bytes using the browser's standard TextEncoder API. Then, we map those bytes into a compatible binary string representation that btoa() can safely process.

Here is how to safely perform a Unicode-safe browser encode and decode in TypeScript without relying on external packages:

/**
 * Safely encodes any UTF-8 string (including emojis and foreign characters) to Base64 in the browser.
 */
export function safeBrowserEncode(input: string): string {
  // 1. Convert the string into an array of UTF-8 bytes
  const utf8Bytes = new TextEncoder().encode(input);
  
  // 2. Map the byte array to a binary-safe string using character codes
  const binaryString = Array.from(utf8Bytes, (byte) => String.fromCharCode(byte)).join('');
  
  // 3. Safely encode the binary-safe string using btoa
  return window.btoa(binaryString);
}

/**
 * Safely decodes a Base64 string back into a fully formed UTF-8 string in the browser.
 */
export function safeBrowserDecode(base64Input: string): string {
  // 1. Decode the Base64 string back into a binary-safe string
  const binaryString = window.atob(base64Input);
  
  // 2. Convert the binary string back into a typed array of bytes
  const bytes = new Uint8Array(binaryString.length);
  for (let i = 0; i < binaryString.length; i++) {
    bytes[i] = binaryString.charCodeAt(i);
  }
  
  // 3. Decode the byte array back to a standard UTF-16 string
  return new TextDecoder().decode(bytes);
}

// This will work flawlessly with Unicode characters!
const unicodeText = "TypeScript is super cool! 🦊 🇺🇦";
const safeEncoded = safeBrowserEncode(unicodeText);
console.log(safeEncoded); // Output: VHlwZVNjcmlwdCBpcyBzdXBlciBjb29sISA🦊 🇺🇦 (encoded)
console.log(safeBrowserDecode(safeEncoded)); // Output: TypeScript is super cool! 🦊 🇺🇦

Building an Isomorphic (Universal) TypeScript Utility

If you are writing code for an SSR framework (such as Next.js, Nuxt, Remix, or SvelteKit), your code runs on both the server (Node.js) and the browser. To handle Base64 operations smoothly in both environments without duplicate logic, you can construct an isomorphic helper:

/**
 * An isomorphic Base64 encoder that executes cleanly on both the server and the browser.
 */
export function isomorphicEncode(input: string): string {
  if (typeof Buffer !== 'undefined') {
    // Node.js Environment
    return Buffer.from(input, 'utf-8').toString('base64');
  } else {
    // Browser Environment
    const utf8Bytes = new TextEncoder().encode(input);
    const binaryString = Array.from(utf8Bytes, (byte) => String.fromCharCode(byte)).join('');
    return window.btoa(binaryString);
  }
}

/**
 * An isomorphic Base64 decoder that executes cleanly on both the server and the browser.
 */
export function isomorphicDecode(base64Input: string): string {
  if (typeof Buffer !== 'undefined') {
    // Node.js Environment
    return Buffer.from(base64Input, 'base64').toString('utf-8');
  } else {
    // Browser Environment
    const binaryString = window.atob(base64Input);
    const bytes = new Uint8Array(binaryString.length);
    for (let i = 0; i < binaryString.length; i++) {
      bytes[i] = binaryString.charCodeAt(i);
    }
    return new TextDecoder().decode(bytes);
  }
}

This pattern allows you to write consistent code that never triggers a ReferenceError: Buffer is not defined on the frontend, nor a ReferenceError: window is not defined on the backend.

3. TypeScript Types for Base64: Going Beyond General Strings

One major content gap in typical web tutorials is that they treat Base64 strings as generic string types. This is highly imprecise. If a function expects a Base64-encoded string, passing an un-encoded string like "hello world" will cause runtime decoding errors.

How do we prevent this at compile-time? We use advanced TypeScript features: Branded Types and Template Literal Types.

1. Branded (Nominal) Types for Base64

TypeScript uses a structural type system (if the shapes match, the types match). By using "branding," we can simulate nominal typing, meaning we tell the compiler that a string is not just any string, but specifically a validated Base64 string.

// Step 1: Create a unique brand symbol
declare const base64Brand: unique symbol;

// Step 2: Define the branded type
export type Base64String = string & { readonly [base64Brand]: true };

// Step 3: Write a type guard to validate Base64 syntax at runtime
export function isBase64(str: string): str is Base64String {
  // Standard Base64 regex pattern
  const base64Regex = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
  return base64Regex.test(str);
}

// Step 4: Create a safe assertion factory function
export function assertBase64(str: string): Base64String {
  if (!isBase64(str)) {
    throw new TypeError(`The provided value is not a valid Base64 encoded string: "${str}"`);
  }
  return str;
}

How does this protect your code? Let's look at an application scenario:

interface ImagePayload {
  id: string;
  filename: string;
  // Using our branded type instead of a standard string
  base64Data: Base64String;
}

function uploadImage(payload: ImagePayload) {
  console.log(`Uploading ${payload.filename}...`);
}

// --- TypeScript Compiler Guard in Action ---

const badPayload = {
  id: "1",
  filename: "avatar.png",
  base64Data: "this-is-plain-text-not-base64"
};

// @ts-expect-error: TS2345: Argument of type 'string' is not assignable to 'Base64String'
uploadImage(badPayload);

// Correct approach:
const rawString = "SGVsbG8sIHdvcmxkIQ=="; // Valid Base64 for "Hello, world!"
if (isBase64(rawString)) {
  const goodPayload: ImagePayload = {
    id: "2",
    filename: "avatar.png",
    base64Data: rawString // TypeScript allows this because of the runtime type guard!
  };
  uploadImage(goodPayload);
}

By leveraging this pattern, you force the developer to validate their data at the boundary layer before passing it down to core application systems.

2. Template Literal Types for Base64 Data URLs

When storing low-quality image placeholders (LQIP), inline CSS backgrounds, or small file attachments, you will often use Data URLs. These strings follow a specific schema: data:[<mediatype>];base64,<data>.

We can restrict strings in TypeScript to strictly match this pattern using Template Literal Types:

// Define custom template literal shapes
export type ImageMimeType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';

export type Base64DataUrl<T extends string = string> = `data:${T};base64,${string}`;

// Usage Example:
const validAvatar: Base64DataUrl<ImageMimeType> = 'data:image/png;base64,iVBORw0KGgoAAAANS...' // Compiles!

// @ts-expect-error: Type '"data:image/png;unsupported,abc..."' is not assignable
const invalidAvatar: Base64DataUrl<ImageMimeType> = 'data:image/png;unsupported,abc...';

// @ts-expect-error: Type '"image/svg+xml"' is not assignable to 'ImageMimeType'
const rawSvg: Base64DataUrl<ImageMimeType> = 'data:image/svg+xml;base64,PHN2Zz...';

This gives you deep, granular type safety when retrieving image representations from headless CMS platforms or assets generated by standard processing pipelines.

4. Advanced Real-World Recipes: Files, Images, and Streams

Let's apply these principles to standard real-world requirements. These utility functions are optimized for TypeScript and ready to be integrated directly into your project codebase.

Recipe 1: Converting a Browser File/Blob to Base64

When implementing a frontend drag-and-drop file uploader, you often need to read the contents of a selected file into memory as a Base64 string to display it locally, or prepare it for a JSON payload request.

/**
 * Converts a native Browser File or Blob into a Base64 Data URL.
 */
export function fileToBase64(file: File | Blob): Promise<Base64DataUrl> {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    
    // Read file contents as a Base64 Data URL
    reader.readAsDataURL(file);
    
    reader.onload = () => {
      if (typeof reader.result === 'string') {
        resolve(reader.result as Base64DataUrl);
      } else {
        reject(new Error('FileReader failed to yield a string representation.'));
      }
    };
    
    reader.onerror = (error) => reject(error);
  });
}

Recipe 2: Writing a Base64 String to a Node.js File

If you are building an Express.js or NestJS server that receives file uploads packaged as Base64 strings, you will want to write them back to local storage as binary files using Node.js's file system module:

import fs from 'node:fs/promises';
import path from 'node:path';

/**
 * Saves a Base64 string or Base64 Data URL directly into a local binary file on the server.
 */
export async function saveBase64ToFile(
  base64Input: string, 
  outputPath: string
): Promise<void> {
  // 1. If it's a data URL, strip out the metadata prefix (e.g., "data:image/png;base64,")
  const rawBase64 = base64Input.includes(';base64,')
    ? base64Input.split(';base64,')[1]
    : base64Input;

  // 2. Resolve target folder and write raw binary buffer out to local disk
  const buffer = Buffer.from(rawBase64, 'base64');
  await fs.mkdir(path.dirname(outputPath), { recursive: true });
  await fs.writeFile(outputPath, buffer);
}

Recipe 3: Creating URL-Safe Base64 Strings (Base64URL)

Standard Base64 strings can contain the characters +, /, and =. However, when passed inside query parameters, URL segments, or inside JSON Web Tokens (JWT), these characters can become corrupted or trigger parser errors because they have native structural roles in HTTP systems.

URL-Safe Base64 (referred to as Base64URL) solves this by replacing + with -, / with _, and removing the trailing padding characters (=):

/**
 * Converts a standard Base64 string into a URL-safe Base64URL string.
 */
export function toBase64Url(standardBase64: string): string {
  return standardBase64
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

/**
 * Converts a URL-safe Base64URL string back into a standard Base64 string.
 */
export function fromBase64Url(base64Url: string): string {
  let standardBase64 = base64Url
    .replace(/-/g, '+')
    .replace(/_/g, '/');
  
  // Restore trailing padding symbols if necessary
  while (standardBase64.length % 4 !== 0) {
    standardBase64 += '=';
  }
  
  return standardBase64;
}

// Example usage:
const standard = "a+b/c==";
const urlSafe = toBase64Url(standard);
console.log(urlSafe); // Output: a-b_c
console.log(fromBase64Url(urlSafe)); // Output: a+b/c==

5. Performance and Security Best Practices

💾 The Base64 Size Overhead (~33% Inflation)

Base64 is not designed to compress data. In fact, it does the exact opposite. Because Base64 uses only 64 safe ASCII characters to represent raw data, it maps every 3 bytes of raw binary data into 4 characters of text. This introduces an immediate, unavoidable size inflation of approximately 33%.

• Rule of Thumb: Avoid storing large physical files (such as high-res video assets or large document archives) directly inside Base64 strings in your databases or transmitting them via API requests. Use cloud-based storage services (like AWS S3) and store raw files in binary format, referencing them in your TypeScript payloads using clean, external HTTP URLs.

⚡ Avoiding Out-Of-Memory (OOM) Errors in V8

Processing huge files (e.g., 100MB+) through standard string-to-base64 functions can quickly allocate massive amounts of physical memory. This is because strings in JavaScript engine engines (V8) are immutable. Every string mutation or buffer allocation creates copies of the underlying memory.

• Solution: For massive file manipulation, use Node.js streams or modern browser Web Streams to read, encode, and write files chunk-by-chunk in a memory-bounded loop.

🔒 Security Alert: Base64 Is NOT Encryption

This is a common security misconception. Encoding data with Base64 is merely a formatting conversion. It provides zero confidentiality or security protection.

• Anyone can instantly parse, read, and manipulate a Base64 string using standard tools. Never store user passwords, credentials, access tokens, or sensitive API keys in plain Base64 configuration files or cookies without employing robust, modern encryption schemes (such as AES-GCM or RSA).

6. Frequently Asked Questions (FAQ)

How do I solve the "Buffer is not defined" error in Next.js or Vite projects?

This error occurs when you run code inside browser environments that was originally intended to run on the server. The Buffer object is a Node.js global class and is not present natively inside browser JS runtimes. To solve this, you can write isomorphic code (as shown in Section 2) that checks typeof Buffer !== 'undefined' before falling back to native browser APIs (TextEncoder and btoa).

Is there a built-in "base64" type in standard TypeScript?

No, TypeScript does not provide a native base64 primitive type. However, you can construct custom types to enforce Base64 formatting at compile-time. As demonstrated in Section 3, you can use Branded Types to create safe nominal string tags, or use Template Literal Types to strictly enforce structural formats like Data URLs.

Why does btoa() throw "The string to be encoded contains characters outside of the Latin1 range"?

This crash occurs when you attempt to parse standard Unicode characters (such as emojis or foreign alphabets) using the browser's raw btoa() method. Because btoa() only supports characters with code points below 255 (single-byte values), passing multi-byte characters causes a mathematical conflict. To resolve this, always encode strings into a UTF-8 typed byte array using TextEncoder before passing the transformed character codes to btoa().

Summary of Key Takeaways

By following this structured approach, you ensure your Base64 operations remain safe, modern, and immune to the common runtime bugs that plague web projects. Your TypeScript compiler will protect you, your performance will remain high, and you can build isomorphic services with complete type safety.