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 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:
<script src="/assets/js/changelog-data.js?v=1.8.12"></script>
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.
SOCIAL SHARE CARD GENERATOR