DEV Community: BellSal

What actually breaks when you process PDFs in the browser

BellSal — Sat, 15 Aug 2026 20:38:57 +0000

Doing PDF work entirely in the browser is a nicer story than it sounds. pdf-lib loads a document from an ArrayBuffer, gives you pages as objects, and hands back bytes — no server, no upload, no retention policy anyone has to trust. The happy path is about fifteen lines.

The unhappy paths are where the actual engineering is, and none of them announce themselves. Here are the four that cost me the most.

Encrypted PDFs can't be modified, and most tools lie about it

This is the one that generates support emails.

A PDF can carry two different passwords. A user password stops you opening the file at all — obvious, and users understand it. An owner password lets anyone open and read the document while restricting what can be done to it. Files that come out of banks, insurers and government portals very often have one, and nothing in the viewer tells you.

pdf-lib will refuse to load such a document:

import { PDFDocument } from 'pdf-lib';

try {
  const pdf = await PDFDocument.load(bytes);
} catch (err) {
  // "Input document to `PDFDocument.load` is encrypted."
}

There is an ignoreEncryption: true option, and it is a trap. It gets you past the exception, and the object you get back is structurally incomplete. Merge it with another document and you produce a file that opens to blank pages, or doesn't open at all. The operation "succeeded" and the output is garbage.

Plenty of online PDF tools take exactly that shortcut. You upload a protected file, the spinner runs, you get a download, and the result is broken — with no explanation, because from the tool's point of view nothing failed.

The honest handling is to detect the condition and say so:

let pdf;
try {
  pdf = await PDFDocument.load(bytes);
} catch (err) {
  if (String(err).includes('encrypted')) {
    throw new UserFacingError(
      'This PDF is password-protected and cannot be modified. ' +
      'Remove the protection in the application that produced it, then try again.'
    );
  }
  throw err;
}

It's a worse-looking outcome and a much better one. "I can't do this, here's why" beats a corrupted file every time.

The memory ceiling is real, and it kills the tab silently

Everything lives in the tab. The original ArrayBuffer, the parsed object graph, the serialised output — at peak you are holding several copies of the document at once. A 300-page scan at 300 dpi is a few hundred megabytes before you've done anything useful, and on mobile the tab just dies. No exception you can catch, no onerror, nothing to report. The page is simply gone.

So the size guard has to come before parsing, not after:

const MAX_BYTES = 100 * 1024 * 1024;

if (file.size > MAX_BYTES) {
  throw new UserFacingError(
    `This file is ${(file.size / 1048576).toFixed(0)} MB. ` +
    `Browser memory tops out well below that — PDFsam or Stirling PDF on your desktop ` +
    `will handle it comfortably.`
  );
}

Naming a tool that does the job better is not a defeat. Someone with a 400 MB scan is not going to be served by any browser, and pretending otherwise wastes their afternoon.

Two things that help below the ceiling: process sequentially rather than loading every input at once, and drop references as you go so the collector can actually reclaim them. Merging ten files one at a time uses a fraction of the peak of merging them in parallel.

"Compress this PDF" means two completely different jobs

Users ask for one thing and mean one of two, and the difference decides whether you can help at all.

If the PDF came from a scanner, there is no text inside it — there's a photograph per page. Ninety-five percent of the weight is images, and compression works spectacularly: re-encoding those images or dropping them from 600 dpi to 200 can take a file down by an order of magnitude, and it stays perfectly readable.

If the PDF was generated from a word processor, the text weighs almost nothing. The size is in embedded fonts and images, and there's very little to win. A tool promising 80% off that kind of file is rasterising it behind your back — turning every page into a picture. The file gets smaller, and the text stops being selectable, searchable and accessible. Most people don't notice until they try to search the document weeks later.

Telling the two apart is cheap. Extract the text; if there's essentially none across the pages, you're looking at a scan:

const looksLikeScan = (extractedChars, pageCount) =>
  extractedChars / pageCount < 50;

Say which one you're dealing with, and what the realistic outcome is. Managing that expectation up front is worth more than any codec.

`pdf-lib` doesn't render, and that surprises people

pdf-lib manipulates document structure — pages, metadata, annotations, form fields. It does not draw anything. If you want thumbnails so users can pick pages before splitting, you need pdf.js, which is a separate library with a separate footprint.

Shipping both is the normal answer, and it roughly doubles what the user downloads before anything happens. Worth loading the renderer lazily, only when a preview is actually requested.

Why do it client-side at all

The honest summary is that it wins on trust and loses on scale.

Every "we delete your files after an hour" promise is a statement about what a company does after receiving your document. It might be entirely true. It's still a promise, and for a signed contract or a medical record that's a decision worth making deliberately rather than by default.

When the work happens in the browser, there's nothing to promise. The request doesn't exist, and anyone can confirm it in ten seconds: open DevTools, Network tab, run the operation, watch nothing leave. That test works on any site, including mine — I run pdfonlinefree.com, which is where all of the above came from.

What you give up is everything that needs real memory or real CPU. Hundred-page scans, batch jobs, OCR. For those, a desktop application is simply the right tool and I'd say so to anyone who asked.

The failure modes are the transferable part. Every one of them is silent by default, and every one of them is a place where the easy implementation reports success while handing the user something broken.

The download button that silently did nothing on mobile

BellSal — Sat, 15 Aug 2026 17:38:15 +0000

For about a year, the save button in my collage editor did nothing on phones. Not "threw an error." Not "downloaded a corrupted file." Nothing at all. You tapped it, the button got its little active state, and then the app just sat there.

Nobody reported it. That's the part that still bothers me. A button that crashes gets a bug report; a button that does nothing gets interpreted as user error. People assumed they'd tapped wrong, tapped again, then left.

The code that looked fine

The editor is vanilla JS drawing to a <canvas>. Everything happens client-side — the images never leave the device, which is the whole point of the thing. So exporting was the textbook approach:

const dataUrl = canvas.toDataURL('image/png');
const a = document.createElement('a');
a.href = dataUrl;
a.download = 'collage.png';
a.click();

This works in every desktop browser. It works in Chrome DevTools' device emulation, which is how it survived so long. It works in a mobile browser often enough that you don't immediately suspect it.

It does not work in an Android WebView, and it does not work in iOS Safari.

The download attribute is a hint, and both of those environments are free to ignore it. An Android WebView has no download manager attached unless the host app wires one up, so the navigation to a data: URL is simply dropped. iOS Safari has historically refused download on data: and blob: URLs from a synthetic click. Neither throws. Neither logs. There is no rejected promise to catch, no event to listen for. The failure mode is a return value of undefined from a function that had one job.

That's what makes this class of bug expensive: you cannot detect it from the JS side. There's no if (downloadWorked). You find it by holding a phone.

Fixing Android: stop pretending it's a browser

The mobile apps are the same editor wrapped in Capacitor, so on Android I had a native layer available and used it. The web code hands the base64 payload to a plugin, and the plugin writes the bytes to shared storage with the platform's own file APIs.

const dataUrl = canvas.toDataURL('image/png');
const base64 = dataUrl.split(',')[1];

await Filesystem.writeFile({
  path: `collage-${Date.now()}.png`,
  data: base64,
  directory: Directory.Documents,
});

Unremarkable, and that's the point. On Android the honest fix was to admit I wasn't in a browser and use the host platform. The user gets a real file in a real folder, which is what they wanted when they tapped save.

Fixing iOS: the Web Share API, and the constraint it doesn't document

iOS has no equivalent escape hatch I was willing to take, so the export goes through the Web Share API instead:

const file = dataUrlToFile(dataUrl, 'collage.png');

if (navigator.canShare && navigator.canShare({ files: [file] })) {
  await navigator.share({ files: [file], title: 'Collage' });
}

Note canShare({ files }) rather than a bare check for navigator.share. Sharing text is widely supported; sharing files is a separate capability, and the feature-detect has to include the payload or it lies to you.

The part that cost me an evening is not in that snippet. navigator.share() requires transient user activation — it must be called during the gesture that triggered it. And that activation is consumed by await. If you write the natural-looking version:

// broken on iOS
button.addEventListener('click', async () => {
  const blob = await new Promise(res => canvas.toBlob(res));
  const file = new File([blob], 'collage.png', { type: 'image/png' });
  await navigator.share({ files: [file] });  // silently dismissed
});

...the share sheet either never appears or flashes and dies. Same signature as the original bug: no error, no console output. The await yielded to the event loop, the activation window closed, and iOS declined without comment.

So the base64-to-File conversion has to be synchronous. canvas.toDataURL() is synchronous, atob() is synchronous, and the File constructor is synchronous — the whole chain can run inside the handler with no yield point:

function dataUrlToFile(dataUrl, filename) {
  const [header, payload] = dataUrl.split(',');
  const mime = header.match(/:(.*?);/)[1];
  const binary = atob(payload);
  const bytes = new Uint8Array(binary.length);

  for (let i = 0; i < binary.length; i++) {
    bytes[i] = binary.charCodeAt(i);
  }

  return new File([bytes], filename, { type: mime });
}

fetch(dataUrl).then(r => r.blob()) is the prettier version of this function and it is unusable here, because it's async. Same for canvas.toBlob(). The ugly charCodeAt loop exists specifically to stay inside the gesture. For a few megapixels it costs a handful of milliseconds, which is a fine trade for a feature that otherwise doesn't exist.

One caveat worth stating plainly: navigator.share() returning without rejecting does not mean a file was saved. It means the sheet was presented. You cannot tell whether the user picked "Save Image," sent it to a chat, or cancelled — the promise resolves the same way. Some visibility is simply not available to you.

The part I'm not happy about

On iOS the user taps a button labelled save and gets a share sheet, where "Save Image" is one option among Messages, Mail, AirDrop and a dozen apps. That is not a download and does not look like one. It's an extra decision at exactly the moment the user thought they were done.

I shipped it because a share sheet is enormously better than nothing, and because the alternative on iOS was a long-press-to-save instruction nobody reads. But I want to be clear that it's a compromise, not a solution. If you're evaluating this approach: the ceiling is "acceptable," not "good."

A second silent failure, same shape

While I was in there, I found a bug with an identical personality in the analytics setup. Google Consent Mode was initialised with defaults denied — correct and required — but the cookie banner that could flip those defaults only rendered for EU visitors, because that's who the compliance requirement targeted.

Read those two facts together: every visitor outside the EU started denied and was never shown any way to consent. They were permanently invisible in GA4. The site looked close to dead in the reports while it was in fact getting traffic.

gtag's consent defaults take a region parameter, and the fix is to scope the denial to the places where the banner actually exists:

gtag('consent', 'default', {
  ad_storage: 'denied',
  analytics_storage: 'denied',
  ad_user_data: 'denied',
  ad_personalization: 'denied',
  region: [
    'AT','BE','BG','HR','CY','CZ','DK','EE','FI','FR','DE','GR','HU',
    'IE','IT','LV','LT','LU','MT','NL','PL','PT','RO','SK','SI','ES',
    'SE','IS','LI','NO','GB','CH'
  ],
});

With a region array, the directive applies only to those countries; visitors elsewhere fall through to whatever your unscoped default is. You still need a real consent flow for the listed regions — this isn't a way to opt out of the banner, it's a way to stop applying a banner's defaults where the banner never runs.

What actually generalises

Both bugs were invisible to every tool I had pointed at the project. No exception, no failed request, no red line anywhere. They were only visible as an absence: a file that never appeared, a country that never showed up in a report.

So the lesson I took isn't about download attributes or consent strings specifically. It's that anything you hand off to the platform — a download, a share sheet, a permission prompt, a consent signal — can be declined in silence, and your code will happily report success. Those handoffs are where I now check the outcome on a real device rather than trusting the call site.

The editor in question is freecollageimage.com, if the context helps. The bugs are the transferable part.