I shipped 29 browser-only image tools. These 5 boring patterns kept the codebase sane

I thought building browser-only image tools would mostly be about Canvas APIs and file formats.

It wasn’t.

The hard part started after tool #3, then tool #12, then tool #29: shared logic that wanted to fork, decoder libraries that were too expensive to load everywhere, export bugs that only showed up on transparent images, hash links that broke on real version IDs, and “fixed” assets that users still couldn’t see because cache visibility was treated as an afterthought.

For the past few weekends I’ve been shipping 24Picture, a free browser-local image toolkit. The stack is intentionally boring: static HTML, ES2020 JavaScript, Canvas, and a few route-specific decoders. No backend image processing. No uploads. Just a growing set of small tools that all need to feel consistent, stay fast, and survive hotfixes without turning into a pile of one-off exceptions.

Here are five patterns that actually held up.

1. One shared dispatcher beats cloned tool logic

The first few tools tempted me into the usual trap: one page, one script, one slightly different copy of the same workflow. That feels harmless at tool #2. By tool #10, it becomes a maintenance tax. By tool #29, it means every upload rule, MIME check, preview behavior, download naming fix, and UX improvement has to be rediscovered in multiple places.

The pattern that held up was much less exciting: one shared dispatcher and one route-to-format matrix.

const ROUTE_MATRIX = {
  'webp-to-png':  { input: ['image/webp'], outputMime: 'image/png',  ext: 'png'  },
  'webp-to-jpg':  { input: ['image/webp'], outputMime: 'image/jpeg', ext: 'jpg'  },
  'png-to-jpg':   { input: ['image/png'],  outputMime: 'image/jpeg', ext: 'jpg'  },
  'tiff-to-jpg':  { input: ['image/tiff'], outputMime: 'image/jpeg', ext: 'jpg', decoder: decodeTiff },
  'tiff-to-png':  { input: ['image/tiff'], outputMime: 'image/png',  ext: 'png', decoder: decodeTiff },
  'ico-to-png':   {
    input: ['image/x-icon', 'image/vnd.microsoft.icon'],
    outputMime: 'image/png',
    ext: 'png',
    decoder: decodeIco
  },
  // …29 routes
};

Each tool page sets a route hint like , and the shared script looks up its row at boot. Adding a new converter becomes “one HTML page + one matrix row” instead of “copy three files and hope nothing drifted.”

The real win isn’t lines saved. It’s that drag-drop, preview, validation, download naming, empty-state copy, and error handling all live in one place. When a UX bug shows up, I fix it once and 29 tools inherit it.

If the user experience is the same, the code path should probably be shared too.

2. Lazy-load the expensive decoders, not the whole site

Not every browser image format is created equal. Some tools only need Canvas. Others need heavier decoders for formats like HEIC, TIFF, or ICO. The mistake would have been treating those libraries as “site-wide JavaScript” and making every visitor pay for them on first load.

Some of the specialized libraries are big enough to matter:

The better rule was simple: if only a small slice of pages needs a decoder, only those pages should load it.

The shared dispatcher only invokes a decoder when its route declares one. The homepage stays lighter, the general tools stay decoder-free, and specialized features stop dragging the entire site down with them.

Don’t let your homepage pay the bundle tax for edge-case formats.

3. JPG export needs a deliberate transparency policy

One of the most boring bugs turned out to be one of the most user-visible: exporting transparent images to JPG. If you don’t make the background policy explicit, the result is whatever the browser gives you — and that often means black where users expected white.

The fix is tiny, but the rule matters more than the code.

function exportJpg(srcCanvas) {
  const c = document.createElement('canvas');
  c.width = srcCanvas.width;
  c.height = srcCanvas.height;
  const ctx = c.getContext('2d');

  ctx.fillStyle = '#ffffff';
  ctx.fillRect(0, 0, c.width, c.height);
  ctx.drawImage(srcCanvas, 0, 0);

  return new Promise(resolve => c.toBlob(resolve, 'image/jpeg', 0.92));
}

The lesson wasn’t just “remember to fill white first.” The real lesson was that format-specific assumptions should never be scattered across multiple tools. If JPG export has a quirk, centralize that logic once and make every *-to-jpg page inherit it.

Format quirks become production bugs when they’re duplicated instead of standardized.

4. A harmless-looking querySelector() can break production navigation

Some bugs don’t look like bugs until real data hits them. One production example came from a public changelog with version IDs like v1.7.2. The smooth-scroll handler fed the raw href straight into querySelector().

// 🔥 will throw on hashes like #v1.7.2
document.querySelectorAll('a[href^="#"]').forEach(a => {
  a.addEventListener('click', e => {
    e.preventDefault();
    const t = document.querySelector(a.getAttribute('href'));
    if (t) t.scrollIntoView({ behavior: 'smooth' });
  });
});

That looked fine until the real IDs contained dots. Then the page started throwing:

Uncaught SyntaxError: Failed to execute 'querySelector' on 'Document':
'#v1.7.2' is not a valid selector.

In CSS, . is a class delimiter, so #v1.7.2 isn’t interpreted as a literal ID. It’s interpreted as something structurally different — and invalid for this case.

The safer fix was to stop being clever:

const t = document.getElementById(href.slice(1));

If I really needed selector semantics, CSS.escape() would also work. But this bug was a good reminder that production identifiers are rarely as clean as demo values. The more direct DOM API is often the more robust one.

Real production IDs don’t care whether your selector assumptions are elegant.

5. Shared asset hotfixes need a visibility strategy, not just cache busting

One of the most frustrating classes of bugs is the kind you already fixed, deployed, and still can’t reliably show to users. On a static site with shared JavaScript, “the file changed” is not the same thing as “the update is visible.”

The reason is that not every shared asset lives in the same caching layer. Some resources are effectively part of your shell and Service Worker lifecycle. Others are just shared runtime files referenced by many HTML pages. Treating both cases as the same problem leads to half-fixes.

For shell-level changes, a Service Worker version bump is still the right lever:

// public/service-worker.js
const VERSION = 'v1.8.11';
const SHELL_CACHE = `app-shell-${VERSION}`;
const RUNTIME_CACHE = `app-runtime-${VERSION}`;

But for non-precached shared assets, visibility often comes from changing the referenced URL and deploying the HTML that points to it:

That distinction mattered a lot on a multi-language static site. A shared data file can be perfectly updated on origin and still appear “stuck” if many pages continue referencing the old path, or if intermediate caches never see a URL change. The question that finally improved hotfix reliability wasn’t “did I bust cache?” It was: which layer is caching this file, which pages reference it, and what exactly has to change before a user can observe the fix?

A hotfix is only real when users can actually see it.

Wrap

None of these patterns are especially novel. That’s exactly why they were worth keeping.

When you ship a lot of small browser tools, the flashy part usually isn’t the hard part. The hard part is making sure the same rules still hold when the codebase grows, when shared assets change, and when one tiny bug suddenly affects twenty pages instead of two.

That’s what made the boring patterns valuable: they kept the project moving without demanding a rewrite every time a new tool or edge case showed up.