DEV Community: Miller Elias

How PDF Merging Actually Works Under the Hood (And Why Most Implementations Mess It Up)

Miller Elias — Mon, 12 Oct 2026 03:50:35 +0000

Merging PDF files sounds like a trivial Sunday afternoon project. Grab file A, grab file B, glue them together, download. How hard could it be?

If you've ever inspected what popular libraries actually do—or worse, tried to write a parser yourself—you know that PDF is not a stream of formatted text. It’s a 30-year-old PostScript-derived, semi-random-access object graph masquerading as a document format.

Let's walk through what actually happens when you merge two PDF files, why naive approaches destroy document fidelity, and how modern browser runtimes can handle the entire pipeline without uploading sensitive files to an external server.

The Naive Trap: Canvas Rasterization

Before getting into the internals, we have to talk about the anti-pattern that plagues far too many open-source projects and SaaS utilities: the rasterization pipeline.

It usually looks like this:

Render each page of Document A onto an HTML5 <canvas> using pdf.js.
Convert that canvas to a PNG or JPEG blob (canvas.toDataURL()).
Re-encode those images into a brand-new PDF using a generator like jsPDF.

[Vector PDF] ──> [Rasterize to 72/150 DPI Bitmap] ──> [Re-wrap into new PDF]

It works on a prototype demo, but in production, it's a disaster:

Text searchability is obliterated: Ctrl+F stops working because glyph strings were converted into flat pixels.
File sizes explode: A 200 KB contract with crisp vector typography suddenly turns into a 35 MB blob of compressed JPEGs.
Print degradation: Vector shapes and true type fonts scale infinitely; rasterized canvases become blurry pixel soup when sent to high-DPI office printers.
Metadata stripped: Hyperlinks, form fields, and bookmark outlines vanish.

To merge PDFs properly, you cannot treat pages as images. You must treat them as object graphs.

What a PDF File Actually Looks Like

At its core (as standardized in ISO 32000), a PDF is divided into four distinct regions:

┌──────────────────────────────────────────┐
│  1. Header (%PDF-1.7)                    │
├──────────────────────────────────────────┤
│  2. Body                                 │
│     1 0 obj << /Type /Catalog ... >>     │
│     2 0 obj << /Type /Pages ... >>       │
│     3 0 obj << /Type /Page ... >>        │
│     4 0 obj << /Length 284 >> stream ... │
├──────────────────────────────────────────┤
│  3. Cross-Reference Table (xref)          │
│     0000000000 65535 f                   │
│     0000000015 00000 n                   │
│     0000000128 00000 n                   │
├──────────────────────────────────────────┤
│  4. Trailer                              │
│     << /Size 5 /Root 1 0 R >>            │
│     startxref                            │
│     1024                                 │
│     %%EOF                                │
└──────────────────────────────────────────┘

Notice the architecture: PDF readers do not read from top to bottom.

When a PDF engine opens a file:

It seeks directly to the last 1,024 bytes to find the %%EOF marker and the startxref pointer.
It reads the byte offset of the Cross-Reference Table (xref) or Cross-Reference Stream.
The xref table tells the engine the exact physical byte positions of every indirect object (1 0 obj, 2 0 obj, etc.) in the file.
It resolves the /Root dictionary (the Catalog), traverses the /Pages tree, and loads only what is needed to display page 1.

Every page is a node inside a tree structure, pointing to resources, content streams, and font dictionaries.

The Real Technical Hurdles of Merging

When you combine File A (10 pages) and File B (15 pages) into a single document, you cannot simply concatenate the byte buffers. Here is what makes combining them non-trivial.

1. Object Number ID Collisions

In File A:

4 0 obj
<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
endobj

In File B:

4 0 obj
<< /Type /XObject /Subtype /Image /Width 600 /Height 400 ... >>
endobj

Both documents have an object numbered 4 0 obj. If you put them in the same file without remapping, the parser hits an ID collision.

The merger must parse the indirect object table, maintain an ID translation map (SourceDocA_Obj4 -> TargetDoc_Obj18), and rewrite every indirect reference (4 0 R -> 18 0 R) across dictionaries, stream descriptors, and arrays.

2. The `/Pages` Hierarchy & Inherited Attributes

Pages in a PDF are not a flat array; they form a tree structure.

          /Pages (Root)
         /             \
    /Pages (Branch)    /Pages (Branch)
     /        \          /        \
  /Page      /Page    /Page      /Page

Here is a common edge case: according to the PDF specification, attributes like /MediaBox (the page width/height), /Rotate, and /Resources can be defined on an ancestor /Pages node rather than on the individual /Page leaf.

If you extract a /Page dictionary from File A that relies on an inherited /Rotate 90 or an inherited font resource from its parent /Pages node, and you clone only the leaf node into the target document without flattening inherited properties, the page will render blank or rotated incorrectly.

A solid merger must traverse up the source document's tree, resolve any inherited attributes, and explicitly hoist them into the newly copied page dictionary.

3. Font Subsets and Duplication

When software like InDesign, Word, or LaTeX compiles a PDF, it rarely embeds full font files. Instead, it embeds font subsets—packaging only the exact glyphs used in the document (often prefixed with a random tag, like XYZABC+Roboto-Regular).

If File A and File B both use Roboto-Regular, their subset dictionaries will have entirely different glyph mapping tables (CMap / ToUnicode).

You cannot blindly merge or deduplicate /Font objects simply because their base names match. Each font subset must either remain isolated as an independent indirect object or undergo full CMap reconciliation to avoid turning characters into garbled question marks.

Doing It Right in Modern JavaScript

Thanks to libraries like pdf-lib, we don't have to write raw byte stream re-mappers by hand for standard workflows. pdf-lib handles object re-indexing, indirect reference translation, and stream cloning purely in memory.

Here is a lean, battle-tested pattern for combining multiple PDF files in modern TypeScript:

import { PDFDocument } from 'pdf-lib';

interface MergeProgressCallback {
  (current: number, total: number): void;
}

/**
 * Merges multiple PDF ArrayBuffers into a single Uint8Array
 * without re-encoding or rasterizing vector streams.
 */
export async function mergePdfBuffers(
  pdfBuffers: ArrayBuffer[],
  onProgress?: MergeProgressCallback
): Promise<Uint8Array> {
  // 1. Create a pristine target document
  const mergedDoc = await PDFDocument.create();

  for (let i = 0; i < pdfBuffers.length; i++) {
    const buffer = pdfBuffers[i];

    // 2. Load the source PDF into an isolated object graph
    const srcDoc = await PDFDocument.load(buffer, {
      ignoreEncryption: true,
      parseSpeed: 1, // Balance between memory footprint and parsing speed
    });

    // 3. Resolve page indices and copy references
    const pageIndices = srcDoc.getPageIndices();
    const copiedPages = await mergedDoc.copyPages(srcDoc, pageIndices);

    // 4. Add pages to the target tree while preserving original MediaBox geometry
    for (const page of copiedPages) {
      mergedDoc.addPage(page);
    }

    if (onProgress) {
      onProgress(i + 1, pdfBuffers.length);
    }
  }

  // 5. Serialize the unified object graph and reconstruct the xref table
  return await mergedDoc.save({
    useObjectStreams: true, // Compresses indirect objects into streams
  });
}

Why this approach works:

Zero rasterization: copyPages transfers raw /Contents streams and referenced font dictionaries directly into the new document catalog.
Dimension preservation: If File 1 is an A4 portrait contract and File 2 is an A3 landscape spreadsheet, each page's native /MediaBox and /CropBox remain untouched. They coexist naturally without artificial margins.
Selectable text: Vector glyph coordinates and /ToUnicode mapping streams stay fully intact.

Memory Management in the Browser

Running this inside Node.js or a Go worker is relatively straightforward because server processes can allocate large heaps. Doing this entirely inside a user's browser tab is where real-world constraints kick in.

A modern browser tab typically hits an Out-Of-Memory (OOM) ceiling when JavaScript heap allocations push past 1.5 GB to 2 GB (especially on mobile WebKit).

When merging 10 files that are 50 MB each, you aren't just handling 500 MB of data:

Each file starts as a File or Blob.
It gets unpacked into an ArrayBuffer.
The parser converts byte streams into JavaScript objects (dictionaries, arrays, numbers).
The new document builds an internal intermediate representation.
The serializer creates a final Uint8Array.

If you hold references to all parsed source documents in a single array simultaneously, your tab will crash.

Practical Optimizations:

Sequential Processing & Garbage Collection: Load, copy, and immediately let the source document fall out of scope before loading the next one.

   // ❌ Bad: Keeps all source docs in memory at once
   const loadedDocs = await Promise.all(buffers.map(b => PDFDocument.load(b)));

   // ✅ Good: One at a time, allowing GC to collect completed source documents
   for (const buf of buffers) {
     const doc = await PDFDocument.load(buf);
     const pages = await mergedDoc.copyPages(doc, doc.getPageIndices());
     pages.forEach(p => mergedDoc.addPage(p));
     // 'doc' can now be garbage-collected
   }

Revoke Object URLs Promptly: When triggering the file download:

   const blob = new Blob([mergedBytes], { type: 'application/pdf' });
   const url = URL.createObjectURL(blob);

   const a = document.createElement('a');
   a.href = url;
   a.download = 'merged-document.pdf';
   a.click();

   // Don't leak the blob in the browser's internal URL store
   setTimeout(() => URL.revokeObjectURL(url), 10_000);

Offloading to Web Workers: Parsing heavy documents can block the main UI thread for several seconds, freezing CSS animations and user inputs. Moving the PDFDocument.load and mergedDoc.save calls into a dedicated Web Worker keeps your UI running at a smooth 60 FPS while background threads crunch byte arrays.

Handling Tricky Edge Cases

If you are implementing this in production, keep these three edge cases on your radar:

Linearized PDFs ("Fast Web View"): Linearized PDFs store a primary hint stream near the front of the file so web viewers can show page 1 before downloading the full file. When merging, linearization tables are invalid and must be stripped; the target file needs a standard xref table reconstruction.
AcroForms (Fillable Forms): If Document A has a text field called first_name and Document B also has a field called first_name, merging them naively can cause field values to overwrite each other. In a production pipeline, form fields either need unique namespace prefixes or should be flattened prior to merging depending on the use case.
Encrypted Documents: Even if a PDF doesn't ask for a password to open, it might carry an "Owner Password" with permission flags that restrict content extraction. Handling this gracefully requires checking isEncrypted flags and notifying the user upfront.

Wrapping Up

Building tools that touch PDFs requires respecting the format's architecture. The moment you step away from lossy image-conversion tricks and start working directly with object trees and byte streams, you get results that are fast, lightweight, and faithful to the original documents.

If you want to see this kind of client-side stream cloning in action without sending documents through a remote cloud queue, you can try out the implementation over at VersaPDF's Merge Tool. It processes the entire pipeline locally in the browser sandbox, illustrating how much heavy lifting modern web runtimes can achieve.

What edge cases have you run into when working with binary document formats in the browser? Let's discuss in the comments below.

Stop Treating Base64 Like Black Magic: A Veteran's Candid Guide

Miller Elias — Fri, 09 Oct 2026 06:52:47 +0000

Let’s be honest for a second: Base64 is one of those primitives almost every developer touches every week, yet an alarming number of people still treat it like mysterious wizardry.
I’ve lost count of how many PRs I’ve reviewed where someone said, "Don't worry, the sensitive token is encrypted with Base64," or watched a junior engineer spend half an afternoon staring at their screen because window.btoa() blew up on a simple emoji.

Let’s pull up a chair, skip the academic jargon, and talk about what Base64 actually is, how the math works in plain English, and the real-world traps you need to dodge in production.

1. It’s Not Encryption (Please Stop Saying That)

First things first: Base64 is NOT encryption. It never was, and it never will be.
Here is the simple analogy: if encryption is a locked steel bank vault requiring a secret key, Base64 is simply folding a letter into an origami crane so it fits into an odd-shaped envelope. Anyone who intercepts the crane can unfold it in two seconds flat.

Why was it invented?

Back when the early plumbing of the internet was laid down, legacy network protocols (like early SMTP email relays) were built strictly for 7-bit ASCII text.
If you tried to send raw binary—like an image or an executable file—through those pipes, intermediate routers would randomly drop the highest bit, mangle carriage returns, or choke on null bytes (\0).

Base64 was the pragmatic survival fix: take any raw binary stream, chop it up, and translate it into a safe, polite subset of 64 standard printable ASCII characters (`A–Z`, `a–z`, `0–9`, `+`, `/`) that no router on earth could misunderstand.

2. The Simple Math: Why 3 Bytes Turn Into 4 Characters

You don’t need a computer science degree to understand the bit-twiddling here. It’s just basic grade-school arithmetic:

A regular byte has 8 bits.
The Base64 dictionary has 64 characters. Because $2^6 = 64$, you only need 6 bits to represent each character.
How do you make 8-bit pieces fit into 6-bit pieces without wasting space? Find the common denominator: 24 bits. Take 3 raw bytes ($3 \times 8 = 24\text{ bits}$). Now slice that exact same 24-bit window into 4 chunks of 6 bits each ($4 \times 6 = 24\text{ bits}$). Look up those 6-bit values in the Base64 index table, and boom: 3 input bytes become 4 printable characters.

Raw Bytes (3 x 8 = 24 bits):
[ 01001000 ]   [ 01101001 ]   [ 00100001 ]  --> ASCII "Hi!"
Re-sliced into 6-bit chunks (4 x 6 = 24 bits):
[ 010010 ]     [ 000110 ]     [ 100100 ]     [ 100001 ]
   ↓              ↓              ↓              ↓
 Index 18       Index 6        Index 36       Index 33
   ↓              ↓              ↓              ↓
   S              G              k              h
---------------------------------------------------------
Output String: "SGkh"

The Inescapable 33% Tax

Notice what just happened? You fed in 3 bytes, and got 4 characters back.
That means Base64 introduces a mathematical, non-negotiable +33.33% payload expansion. If you convert a 9 MB image into Base64, you now have a 12 MB string traveling across the wire. Always factor this in before embedding assets into an API response!

What’s with the `=` at the end?

If your input doesn't divide evenly by 3, you’ll have 1 or 2 leftover bytes. The encoder pads the missing bits with zeroes and slaps one or two = characters on the tail (= or ==).

Historically, this was just a courtesy flag telling older parsers: "Hey, ignore the extra zero padding at the very end."

3. The URL Trap: Standard Base64 vs Base64URL

Here’s a classic gotcha that has triggered countless late-night production incidents:
Standard Base64 reserves two special punctuation characters: + and /.
Now imagine you take a signed token or user payload, encode it with standard Base64, and pass it as a URL query parameter:

https://myapp.com/confirm?token=ab+cd/ef==

Here is what goes wrong:

The HTTP server interprets + as an encoded space (" ").
Your routing framework sees / and treats it as a path delimiter.
The = sign collides with key-value query parameter parsing. By the time your backend code reads token, the string is already corrupted. Your cryptographic signature verification fails, and you're left debugging ghost errors. The Fix: Always use Base64URL (RFC 4648 §5) on the web. It simply swaps + for -, swaps / for _, and strips the trailing = padding entirely. This is why JSON Web Tokens (which start with eyJhbGci...) look so clean—they are strictly Base64URL. --- ## 4. The JavaScript Landmine: Why btoa() Hates You If you write JavaScript in the browser, you’ve probably tried this in your console:

window.btoa("Hello, World 🚀");
// 💥 Uncaught DOMException: Failed to execute 'btoa' on 'Window': 
// The string to be encoded contains characters outside of the Latin1 range.

Why does it crash?

window.btoa() is a legacy API from the early browser days. It strictly expects single-byte characters within the Latin-1 range (ASCII 0 to 255). The second you feed it a Chinese character, an accented letter, or a modern emoji, its UTF-16 code point exceeds 255, and the runtime immediately throws an InvalidCharacterError.

How to do it cleanly today

Forget fragile legacy hacks like unescape(encodeURIComponent()). Modern browsers give us the native TextEncoder API:

// Robust UTF-8 to Base64 Encoder
function toBase64(str) {
  const bytes = new TextEncoder().encode(str);
  const binString = Array.from(bytes, (byte) => String.fromCharCode(byte)).join('');
  return window.btoa(binString);
}
// Robust Base64 to UTF-8 Decoder
function fromBase64(base64) {
  const binString = window.atob(base64);
  const bytes = Uint8Array.from(binString, (char) => char.charCodeAt(0));
  return new TextDecoder().decode(bytes);
}
console.log(toBase64("Hello, World 🚀")); 
// Outputs cleanly: "SGVsbG8sIOS4lueVjCDwn5mp"

By serializing the string into an explicit array of 8-bit UTF-8 octets first, every single byte fed to `btoa` is guaranteed to stay within `0..255`.

5. Stop Stuffing Big Images Into Data URLs

Every frontend developer discovers data:image/png;base64,... and thinks: "Awesome! I can save an HTTP request by embedding the image directly in my CSS or JSON!"
Here is the reality check:

You destroy browser caching: If an image lives as an independent static file, the browser caches it aggressively via HTTP headers. When embedded into an API response or CSS, users re-download that payload on every single page request.
You blow up bundle size: Remember that 33% expansion tax? A 300 KB image turns into 400 KB over the wire.
You punish the JS engine: Giant string allocations inside JSON payloads force browser memory managers and garbage collectors (GC) to work overtime. Rule of Thumb: Only use Data URLs for micro-assets under 2 KB (like tiny placeholders or inline SVGs). Store everything else in object storage behind a CDN. --- ## 6. A Sanity Check on Debugging When you're knee-deep in debugging—checking an Authorization: Basic header, inspecting webhook payloads, or testing an API response—you just want to quickly encode or decode a string. A critical security reminder: Never paste sensitive production credentials into random, unverified online tools. Many ad-filled converter sites send your inputs to a remote backend server, meaning your customer tokens and auth headers could sit in third-party server access logs. When I need to inspect Base64 strings quickly, I stick to tools that run 100% client-side in the browser. CodeKivo's Base64 Encoder & Decoder is a great example of doing this right:
100% In-Memory Execution: Operates entirely within your local browser sandbox—zero network requests, zero remote logging.
Full UTF-8 & Emoji Support: Handles multi-byte Unicode strings cleanly without throwing Latin-1 errors.

- One-Click URL-Safe Toggle: Instantly switches between RFC 4648 Standard and Base64URL formats so you don't have to manually swap `-` and `_`.

Summary

At the end of the day, Base64 isn't complicated once you understand its purpose:

It's a courier, not a bodyguard: Never use it to hide sensitive data.
Account for the 33% bloat: Don't blindly embed binary files into JSON.
Use Base64URL in web requests: Save yourself from URL-escaping nightmares.
Normalize Unicode before calling btoa(): Always use TextEncoder. Master these basic fundamentals, and you’ll spend far less time troubleshooting silly production bugs.