“File too large” is a design problem, so I spent five months fixing it

You have seen it. Everybody has seen it.

You are on a government website, or a bank, or a school portal, at the very end of a long form. You take a photo of the document they asked for. You press upload. And the page says, very calmly, file too large.

It does not tell you how large is too large. It does not offer to fix it. It just sits there, a little smug, waiting for you to go and become an image engineer.

So you do what everyone does. You search the app store for a photo compressor. You find forty of them. The first one shows you an ad before it opens. The second one wants a weekly subscription. The third one uploads your passport photo to a server you will never see. And somewhere around the fourth one you start to wonder why this is your job at all.

That question is where Compresso started.

Noticing the pattern

I spend a lot of my time thinking about why simple things on screens feel hard. Not hard as in complicated. Hard as in I did everything right and it still did not work, and I do not know why.

Upload forms are the purest example I know. The task is tiny. The failure rate is not. And when I looked closely, the failures kept following the same shape. The system has a rule it could easily handle itself, like a maximum file size or a required format, and instead of handling it, it hands the rule to the person, with no explanation, and walks away.

I started calling that externalized processing: when a system quietly moves work it could do onto the person using it. Compressing a photo is the textbook case. The server knows the limit. The browser knows how to shrink an image. The only one in the room who does not know how is the human.

Thinking about it until it became a paper

I could not stop thinking about it, which in my experience is the only reliable sign that you should write something down.

So I wrote a paper, Cognitive Distance in Document Submission Systems. It looks at upload flows through an idea I had been developing for a while, cognitive distance, which is the gap between how a system is built and how a person understands it while they use it. A form can be short, fast and technically flawless and still be far away from the person filling it in. File too large is a perfect little machine for creating distance.

That idea eventually grew into a whole book, From Cognitive Load to Cognitive Distance, which is free to read at book.izaias.xyz. The short version of it is this: we have spent decades making interfaces less effortful, and much less time making them less far. Those are different problems, and the second one is where people quietly give up.

But a paper only describes a problem. At some point you have to go and move the system closer to the person.

Building the library

The first thing I built was the smallest possible honest answer: a JavaScript library that compresses an image right in the browser, before it is ever uploaded.

I called it Compresso. Then I went to publish it on npm and discovered that compresso was taken. So I tried compressojs. Then I decided that looked like a typo and settled on compresso.js, which is how I learned that naming is the hardest problem in computer science, and also in my life.

The rules I gave it were strict. It uses the codecs the browser already has, so there is almost nothing to download. It picks the best format your browser can actually produce, trying AVIF, then WebP, then JPEG. It reads iPhone HEIC photos. And it makes one promise I care about more than any feature: the result is never bigger than what you gave it. If it cannot make your photo smaller, it gives your photo back.

My goal was for the whole thing to be about 2 KB. When version 1.0 shipped and I actually measured it, it was 3.6 KB. For a compression library, being off by 80 percent on your own size is a special kind of humbling. I fixed the README and kept the lesson: measure first, then brag.

Version 1.0 also learned to work in parallel, spreading a batch of photos across background workers so the page never locks up while it thinks.

Building the web app

A library is a gift for developers. My parents are not developers.

So the next step was an app anyone could open: drop in a hundred photos, watch them shrink at the same time, take them back. No account, no upload bar, no server. Install it once and it keeps working on a plane.

Building it taught me something uncomfortable. I tested the original tool on my own website with a big iPhone photo, and the tab froze for around twenty seconds. Same codec, same photo, and the new app finished in under a second. The only difference was where the work happened. On the website it ran on the main thread and blocked everything. In the app it ran in workers. It is a strange feeling to be beaten by your own project, but it is a very effective way to learn where the work belongs.

Building the website

Then came the website, compresso.izaias.xyz, with a live playground, a calculator for how much bandwidth smaller images save, and documentation in English, Spanish and Portuguese.

The website exists to answer one question for a developer in about ten seconds: can I drop this into my upload form today? The answer is yes.

Building the phone apps

And then I did the thing I had been avoiding. I went back to the person at the end of the long form, holding a phone, and built for them.

The Compresso app for Android and iPhone starts with a question instead of a slider: what is this photo for? A message, an email, an upload form, or saving space. You choose, and it picks the size and quality for you. Then it shows you a before and after so you can check it still looks right. It keeps the date and location only if you want it to. Big buttons, seven languages, works offline, and your photos never leave the phone.

It is free, it is open source, and there are no ads and no subscriptions. Not free for now. Just free.

Apple approved the TestFlight build. Google approved the closed test. And then Google explained the last rule, which I find genuinely charming: before a new Android app can be published to everyone, at least 12 people have to keep it installed for 14 days in a row. If someone leaves early, their two weeks start over.

For a big company, that is a rounding error. For an independent developer building something free, it is the entire launch.

Why I think this belongs in the browser

Here is the dream, and I am saying it out loud so I have to follow through.

Browsers have done this before. For years, if you wanted to gzip something in a web page, you shipped a library like pako to do it. Then the platform noticed everyone needed it and built CompressionStream right into the browser. Userland proved it, the platform absorbed it, and nobody has to think about it anymore.

I think image compression for uploads is the next one. When a form says it accepts photos up to 2 MB, the browser already knows the limit and already knows how to shrink the photo. It should just do it, privately, on the device, and never hand the problem to the person at all.

Compresso is my attempt to build that idea for real first: to find out what the boring, stable version of it looks like, which questions a standard would have to answer, and which promises, like never bigger than the original, are worth making at the platform level. One day I plan to write it up properly and send it to the W3C. Maybe they will say no. That is fine. The worst outcome is that a lot of forms get a little kinder in the meantime.

How can I try Compresso?

Early access for Android and iPhone is open here: compresso.izaias.xyz/early

Leave your email, pick your phone, and the invite arrives in about a minute with one tap per step. On Android, if you can keep it installed for 14 days, you are personally helping it reach the Play Store. On iPhone it installs through TestFlight on iOS 16.4 or later.

Is Compresso really free and private?

Yes. Compresso is a free, open source photo compressor. It works offline, it has no ads and no account, and your photos are compressed on your own device and never uploaded. The code is public at github.com/iziuqo/compresso, and the library is on npm as compresso.js.

Can I use it in my own website?

Yes, and that is the part I am proudest of. If you run an upload form, compresso.js can shrink photos in the browser before they ever reach your server, so your users never meet file too large again.

If you try the app, the most useful thing you can tell me is the moment you hesitated. Reply to your invite email and it comes straight to me. And if you have ever stood at the end of a long form, phone in hand, staring at two smug words, I built this for you.