How I built offline PDF processing with pdf-lib and pdf.js in the browser
Every "free online PDF tool" does the same thing: you drag a file into the page, and that file is uploaded to a server you'll never see, in a region you can't name, for a retention period nobody specifies.
I wanted a PDF toolbox that never uploads anything. Not "we delete it after an hour" - never sends it at all. That meant all parsing, modification and serialization had to happen inside the browser tab. This is what that architecture looks like, and where it gets painful.
The constraint that shapes everything
Once you decide the file can't leave the device, a few things become impossible:
- No server-side Ghostscript for compression
- No server-side qpdf for encryption
- No "process in the background and email you the result"
- No file size limit that only exists because of your server's disk
Everything has to run in a single tab, with the memory a mobile browser is willing to give you. That constraint dictates the entire library choice.
Two libraries, two very different jobs
The split that ended up working:
pdf-lib- writing. Merge, split, rotate, delete pages, watermark, encrypt. It gives you a mutable document model and serializes it back to bytes.pdf.js- reading. Rendering thumbnails and page previews so users can pick pages before operating on them.
Both are vendored and inlined into the HTML. No CDN, no dynamic import. The page works from a cold cache with the network off.
Getting pdf.js to run without a bundler
pdf.js needs its worker. The usual failure is a cross-origin worker URL, which browsers refuse to construct:
// fails in most browsers when the script is served from another origin
pdfjsLib.GlobalWorkerOptions.workerSrc = 'https://cdn.example.com/pdf.worker.min.js';
The fix that works everywhere, including file://-ish and offline scenarios, is to build the worker from a blob:
const blob = new Blob([pdfjsWorkerSource], { type: 'application/javascript' });
pdfjsLib.GlobalWorkerOptions.workerSrc = URL.createObjectURL(blob);
pdfjsWorkerSource is the worker bundle as a string, inlined at build time. Costs you about 1MB of HTML, buys you zero network requests and no CORS surprises.
Merge, split, rotate: the easy 10%
pdf-lib's document model is genuinely pleasant here. Merging is copy-pages:
async function mergePdfs(files) {
const out = await PDFLib.PDFDocument.create();
for (const file of files) {
const bytes = await file.arrayBuffer();
const src = await PDFLib.PDFDocument.load(bytes);
const pages = await out.copyPages(src, src.getPageIndices());
pages.forEach(p => out.addPage(p));
}
return out.save(); // Uint8Array
}
Split and rotate are variations on the same theme. If your tool only did these, you could ship in an afternoon. The interesting problems are compression and encryption.
Compression: pdf-lib does less than you think
Here's the part that surprises people. pdf-lib cannot re-encode embedded images. It has no JPEG/JPEG2000 decode pipeline, no downsampler. When you call save(), it applies FlateDecode to content streams and leaves image streams alone.
So "compress PDF in the browser" really means: strip redundancy from the streams you can touch, and accept that a scan-heavy PDF won't shrink much. The implementation that actually produced useful results was to re-deflate streams myself with pako at a chosen level:
// pdf-lib's internal pako defaults to roughly level 6.
// Re-deflating lets us expose a real Low/Medium/High choice.
function reCompressStreams(pdfBytes, level) {
const doc = PDFLib.PDFDocument.load(pdfBytes, { updateMetadata: false });
// for each content stream: inflate -> deflate at `level`
// (pdf-lib exposes the parsed objects; raw stream re-encode is done manually)
}
Two honest caveats I had to surface in the UI:
- Low compression can make the file bigger. If the original was deflated at level 9, re-deflating at level 1 grows it. That's not a bug, and pretending otherwise produces angry users.
- Image-heavy PDFs barely move. A 20MB scanned document is 19MB of JPEG. Flate won't help. Telling the user "this file is already image-compressed, expected savings are small" is better than silently returning a 19.8MB file.
Encryption: pdf-lib has none
This is the biggest gap. pdf-lib explicitly does not implement the PDF standard security handler (it's issue #243 in the repo, open for years). It can read an encrypted file with ignoreEncryption: true, but it cannot decrypt it properly or write one.
So encrypt/decrypt runs through a separate layer that implements the ISO 32000 standard security handler on top of pdf-lib's parsed object graph, using the Web Crypto API:
// key derivation is the fiddly part - AES-256 (R6) or RC4-128 (R4)
// AES-CBC for R6, per the spec's block format
const key = await crypto.subtle.importKey('raw', fileKey, { name: 'AES-CBC' }, false, ['encrypt', 'decrypt']);
Three things bit me here:
- Object streams.
pdf-libdecompresses object streams at load time and you can't see the original structure. If a producer stores the encryption dictionary inside a compressed object stream, you get a file you can't safely rewrite. The layer has to detect this and refuse rather than emit a corrupt PDF. - Key length is derived from
/Length, not assumed. A file encrypted with 40-bit RC4 and a file with AES-256 need completely different code paths. Hardcoding one silently produces files that open in some readers and fail in others. - Empty user password is common. Plenty of "protected" PDFs are decryptable with an empty password - they only carry an owner password. Handling that case turns a scary error into a one-click fix.
Memory is the real ceiling
Mobile browsers are where this design gets tested. A few things that matter:
- Every
arrayBuffer()you hold is a full copy of the file. Two copies of a 200MB PDF will kill an iOS tab. PDFDocument.load()keeps the whole object graph in memory. There's no streaming mode.- Result blobs should be released.
URL.createObjectURL()leaks for the lifetime of the document unless yourevokeObjectURLit.
The practical limits I settled on are conservative, and I check navigator.deviceMemory where available to warn earlier on low-end Android rather than letting the tab get OOM-killed.
Making it genuinely offline
Being client-side isn't the same as being offline. Two more pieces:
- A service worker with cache-first for static assets, and network-first for the licence API:
if (url.pathname.startsWith('/api/')) {
event.respondWith(fetch(event.request)); // never cache auth
return;
}
- Everything inlined in one HTML file. Roughly 3.2MB, which sounds bad and mostly isn't: it's one request, cached once, and every subsequent tool opens instantly because the libraries are already parsed.
The tradeoff is real though - I can't tree-shake, and every code change to a shared utility touches a 3MB file.
What I'd do differently
- Split the libraries out behind a lazy import once the page is cached by the SW. Inlining wins the first load, loses on maintainability.
- Put compression in a Web Worker from day one. Long
save()calls block the main thread, and a frozen tab on a 50MB file looks like a crash. - Test on a 200MB file before writing the UI. It changes the whole interaction model - you need progress, cancellation, and a hard refusal path.
Was it worth it? For this specific product, yes, because "your files never leave your device" is the entire value proposition, not a feature bullet. If you're building a PDF tool where the upload is incidental, a small server with Ghostscript and qpdf will beat this approach on both quality and code volume.
But if the promise is the privacy, the browser can keep it. You just have to give up the two tools that do the heavy lifting on the server, and be honest about what's left.
If you want to see the result: ipdfverse.com. The tools are offline; the article above is the architecture behind them.
Comments
No comments yet. Start the discussion.