Every "merge PDF" site asks you to upload the file first. That is a strange
trade for a 40 MB contract. Merging is a byte-level operation; it does not
need a server. I have been doing it client-side with pdf-lib for a while,
and the interesting part is not the merge itself — it is everything
copyPages silently leaves behind.
copyPages copies a page, not a document
copyPages gives you the page dictionary and its content stream. It does
not give you the document structures that live in the catalog:
- Outlines. Bookmarks in
/Outlinesbelong to the source document. After merging, they are gone. Your 300-page manual becomes an un-navigable slab. - Page labels. The
/PageLabelsnumber tree is what makes a PDF show "iv, v, vi, 1, 2, 3" instead of "1, 2, 3, 4, 5, 6". It does not survive. - AcroForm fields. Widget annotations travel with the page, but the field dictionary lives at document level. Result: the form renders, looks fine, and is not fillable — or worse, two source documents used the same field name and the merged document now has a duplicate-key problem.
- Embedded files.
/EmbeddedFilesin the name tree is document level. - Structure tree. For tagged PDFs, the accessibility tree is rebuilt from scratch or dropped entirely.
None of this throws an error. That is the trap: the output opens, renders
correctly, and is quietly poorer than the inputs.
The good news: image streams are copied, not re-encoded
This is why local merging beats most server tools. A scanned page is one
JPEG or JBIG2 stream inside the PDF. copyPages moves that stream
byte-for-byte. A 12 MB scan comes out of the merge still 12 MB, with zero
generation loss. Server-side mergers frequently rasterize pages to normalise
them, which re-compresses every scan in the file.
Two save flags worth knowing
const bytes = await merged.save({ useObjectStreams: false, updateFieldAppearances: false, }); `useObjectStreams: true` (the default) makes a smaller file by packing objects into compressed streams. Most modern viewers handle it, but older print RIPs and some preflight tools do not. If the merged file is going to a print shop, turn it off. `updateFieldAppearances: false` skips regenerating form field appearances, which is a measurable saving on documents with many fields. ## Encrypted inputs will produce garbage, not an error const doc = await PDFDocument.load(bytes, { ignoreEncryption: true });
The flag name is misleading. It does not decrypt anything. It lets the parser read a file whose object streams are encrypted, which means `copyPages` will happily copy ciphertext and produce a document that looks merged and renders as noise. Check `doc.isEncrypted` and refuse with a clear message instead of shipping a corrupt file. ## Memory is the real ceiling Five 20 MB PDFs is not 100 MB of memory. Each file is parsed into an object graph, and `Uint8Array` copies are not free. A rough multiplier of 3–5x on file size is realistic at peak. Keep one source document alive at a time, revoke blob URLs when the download starts, and never route bytes through base64 — that adds 33% for no benefit. That is the whole architecture of [merging PDF files in the browser](https://privacypdf.org/merge-pdf/): read the files, merge locally, download, and never touch a network socket. ## When merging is the wrong operation If bookmarks, page labels or fillable forms matter, merging is the wrong primitive. You want to rebuild the outline in the target document deliberately, page by page, with your own numbering. That is more work, and it is the only way to get a merged file that behaves like a real book. 


