DEV Community: RAXXO Studios

Scheduled Jobs and Time Zones: The Midnight Bug I Keep Seeing

RAXXO Studios — Wed, 21 Oct 2026 20:49:32 +0000

Cron runs in UTC by default, so a "midnight" job can fire on the wrong local day
Define the business day explicitly with a timezone string, never a UTC offset
DST shifts your offset twice a year, which silently moves job times by an hour
Test the four edge cases: midnight, month boundary, spring-forward, fall-back

A report that was supposed to cover Monday landed with Sunday's data. The job ran at midnight, the clock just disagreed about which midnight. I've now seen this exact bug in four different codebases, and it's always the same root cause.

Cron thinks in UTC. Your users think in their own kitchen clock. Those two things drift apart in ways that only show up at the edges.

Why Midnight Is the Worst Possible Time to Run a Job

Here's the setup that bites everyone. You want a daily summary of yesterday's orders. You schedule it for "midnight." On a server set to UTC, that's 0 0 * * *. It looks fine in review and ships.

Then someone in Berlin opens the report.

In summer, Berlin is UTC+2. Your midnight UTC job fires at 02:00 Berlin time. So far harmless. But the logic inside the job usually does something like "give me everything from yesterday," and "yesterday" gets computed from the server clock. If the server is UTC and the business lives in Berlin, the window is off by two hours on both ends. Orders placed between 22:00 and 00:00 Berlin time on Monday get filed under Tuesday.

Now flip it. A customer in Los Angeles (UTC-8 in winter) places an order at 23:30 their time on the last day of the month. On the UTC server, that's already 07:30 the next day, next month. Your monthly rollup drops it into the wrong month entirely. Nobody notices until accounting asks why the totals don't match.

The reason midnight is the villain is that it's the one time where a small offset flips the calendar date. A 15-minute delay at 14:00 changes nothing you care about. The same delay at 23:58 changes the day, and sometimes the month, and twice a year it changes by a whole hour on its own.

I've started treating any job scheduled near 00:00 as a code smell.

Not wrong, but worth a second look. Nine times out of ten the person wrote 0 0 because it felt tidy, not because midnight meant anything to the business.

If your scheduled job also talks to an external service that might retry it, the date confusion compounds. I wrote up the safe pattern for that in Writing Idempotent Webhooks, and the same discipline applies here: assume the job can run twice and land on two different calendar days if you're not careful.

Define the Business Day on Purpose, Not by Accident

The fix starts with a decision, not with code. What timezone is the business day measured in? Write it down. Put it in config as a string.

Use an IANA timezone name like Europe/Berlin or America/Los_Angeles. Don't use UTC+2. A fixed offset is a lie for half the year, because the offset changes when daylight saving kicks in. The name encodes all the rules; the offset encodes a single frozen moment.

Once you have that string, stop asking the server what time it is. Compute your reporting window in the business timezone, then convert to UTC only when you query the database.

In practice that looks like this. You want "yesterday in Berlin." You take now, convert it to Europe/Berlin, subtract a day, snap to the start of that day, and snap to the start of the next day. Those two instants are your window boundaries. Then you convert both to UTC for the actual query, because your timestamps are almost certainly stored in UTC. If they're not, that's a separate fire to put out first.

The key move is that the window is defined in local time and the query runs in UTC. People keep collapsing those two steps into one and that's where the bug lives.

I keep a tiny helper for this so I never hand-roll the math. Something that takes a timezone string and a date and returns { startUtc, endUtc }. One function, one test file, reused everywhere. The alternative is scattering new Date() and manual hour arithmetic across six jobs, and each copy drifts slightly until they all disagree.

Schedule the cron trigger in UTC still.

That part's fine. The trigger time and the data window are different concerns. Run the trigger a safe distance from midnight (I like 03:00 or 04:00 local, converted to UTC), and let the window logic figure out which day it's reporting on. A late trigger then can't change the answer, because the answer doesn't depend on when the job actually fired. It depends on the explicit window you computed.

This is the same instinct as validating inputs before you trust them. I go deeper on drawing those boundaries in Request Validation at the Edge.

Daylight Saving Is the Bug That Hides for Six Months

Your job runs fine for months. Then on a Sunday in late March or late October, something's an hour off. Welcome to DST.

Two things happen. In spring, clocks jump forward, so 02:00 to 03:00 doesn't exist. In autumn, clocks fall back, so 02:00 to 03:00 happens twice. If you scheduled a local-time job inside that window, it either skips or doubles.

That's exactly why you should schedule the cron trigger in UTC, which has no DST, and compute the window in local time. UTC marches forward one second at a time, forever, no jumps. Your trigger is stable. The local window shifts by an hour across the DST boundary, which is correct, because the business day genuinely is an hour shorter or longer on those two days.

Here's the part people get wrong even after they've fixed the first bug. They store a UTC offset for the business, say +01:00, and reuse it all year. From late March to late October in Berlin the real offset is +02:00. So for about seven months, every window is an hour off. It looks fine in winter when they test it, and goes quietly wrong in summer.

The name Europe/Berlin carries the rule that the offset is +01:00 in winter and +02:00 in summer, and it knows the exact instants where it flips. Any decent date library with timezone support will apply that for you. You just have to feed it the name, not the number.

One more trap. The hour that occurs twice in autumn is ambiguous. "01:30 local" maps to two different UTC instants on that night. If your window boundary lands there, pick a convention (most libraries default to the earlier instant) and make sure your test asserts which one you got. Don't leave it to chance.

I'll be honest, I don't trust myself to reason about these by hand.

I write a test that pins a fake clock to a specific UTC instant on a DST night and checks the window boundaries come out right. The test is the only thing I trust when the next DST change rolls around and I've forgotten all of this.

The Four Tests That Catch Everything

You don't need a hundred cases. You need four, each pinned to a fixed instant so the test gives the same answer forever.

Test one is plain midnight. Set the clock to 00:30 local time and check that "yesterday" is actually the previous calendar day. This catches the off-by-a-day error where a late-firing job or a careless window calculation rolls into the wrong date.

Test two is the month boundary. Set the clock to 00:30 local on the first of the month and confirm "yesterday" lands in the previous month, and that a monthly rollup includes the right 28, 30, or 31 days. This is where the Los Angeles customer at 23:30 gets lost if your window is computed in UTC.

Test three is spring-forward. Pin the clock to the DST gap night and check that the window still spans a full local day even though that day is 23 hours long in real time. The start and end boundaries should be correct instants, not naive hour math.

Test four is fall-back. Pin to the night with the repeated hour and check your window handles the 25-hour day and picks a consistent instant for the ambiguous boundary.

Run these with a frozen clock.

Real new Date() makes tests that pass today and fail next October. Inject the current time as a parameter, or use a library that lets you set a fake system time. Then assert on exact UTC instants, not on strings, because string formatting adds its own timezone confusion on top.

I keep these four as a template and copy them into any project that has scheduled jobs. The edge cases don't change between projects. Only the timezone string and the window function do. Writing them once and reusing them is the whole point, the same way I reuse a structure for articles so I don't rebuild it each time, which I described in The Blog Post Structure I Use.

If you also schedule social posts off the back of these jobs, the same timezone logic applies to when they publish. A tool like Buffer handles the posting side, but the "which day's content" decision still has to be made correctly upstream.

Bottom Line

Pick the business timezone, store it as an IANA name, and compute your reporting window in that zone before converting to UTC for the query. Trigger the cron in UTC and keep it away from midnight so a late run can't change which day you report. Then write the four tests with a frozen clock and stop reasoning about DST in your head.

If I were starting a new scheduled job today, I'd write the window function and its tests before the job logic. The logic is the easy part. The dates are where the money goes missing.

For how I wire up the agent that scaffolds this kind of helper and its tests in one pass, the Claude Blueprint walks through the setup I use. Start there, then drop in the four tests above, and the midnight bug stops being a thing you ship.

This article contains affiliate links. If you sign up through them, I may earn a small commission at no extra cost to you. (Ad)

Profiling Liquid: How I Find What Slows a Shopify Page

RAXXO Studios — Tue, 20 Oct 2026 20:48:15 +0000

Theme Inspector shows per-section render time right in Chrome DevTools
Server-Timing header reveals Liquid vs network in one number
Nested loops over full collections are the usual slow culprit
Cached snippets with the render tag cut repeat work to near zero

A product page that took 900ms to render Liquid dropped to under 200ms once I found the one section eating the whole budget. The fix wasn't clever. It was a loop inside a loop over a 400-product collection. Here's how I find that kind of thing instead of guessing.

Start with the numbers the theme already gives you

Before touching any code I want one honest number: how long does Liquid take to render this page on the server? Shopify hands you that number in two places, and I check both.

The first is the Shopify Theme Inspector for Chrome. Install the extension, log into your store, open DevTools, and you get a flame graph of every Liquid partial on the page with its render time. Sections, snippets, the lot. You can see that your header took 4ms and your "recommended products" section took 310ms, and suddenly you know where to look.

The second is the Server-Timing HTTP header. Open the Network tab, click the document request, and look at the Timing breakdown. Shopify reports the Liquid processing time there as a server timing entry. This is the number that matters because it's measured on their machine, not yours. Your laptop being slow doesn't move it.

I treat these two as a pair. The header tells me the total damage. The inspector tells me which section did it.

One thing I learned the hard way: measure a warm page, not a cold one. The first request after a theme edit or a deploy can be slower because Shopify hasn't cached the compiled template yet. Load the page twice and read the second number. If I skip this step I end up "fixing" a section that was never the problem.

I also measure a real page, not a demo. A collection page with 8 products behaves nothing like the same template with 400. The slow loop only shows up under real data.

If you want the deeper context on why I keep all of this in files I can profile, see Why Every RAXXO Section Lives in Code, Not the Customizer. You can't profile what the customizer hides from you.

So the routine is simple. Open the page, read Server-Timing for the total, open the inspector for the breakdown, and write down the three slowest sections. Those three are my entire to-do list. Everything else can stay exactly as it is.

Nested loops are almost always the real cost

Once I know the slow section, the first thing I look for is a loop inside a loop. This is the single most common performance bug I find in themes, including ones I wrote.

Here's the shape of the problem. You loop over products in a collection. Inside that loop, for each product, you loop over all its variants. Inside that, maybe you loop over variant metafields. Three products and four variants is nothing. Four hundred products with six variants each is 2,400 inner iterations, and Liquid runs every one of them on the server before a single byte reaches the browser.

The fix is usually to stop doing work you don't need. If I'm showing a product card, I don't need every variant. I need the first available one and maybe the price range, and both of those are available without a loop. product.price_min and product.price_max give me the range directly. product.selected_or_first_available_variant gives me the one I actually show.

The other nested-loop trap is filtering inside the loop. I've seen code that loops over a full collection and then uses an if to show only products with a certain tag. That means Liquid still iterates the whole collection even if only 12 products match. Better to narrow the data before the loop.

Shopify's where filter helps here. collection.products | where: "type", "Poster" hands you a smaller array, and now your loop runs over 12 items instead of 400. The filter happens once. The loop runs fewer times. Both wins compound.

Limits matter too. for product in collection.products limit: 8 stops the loop after 8 iterations no matter how big the collection is. On a homepage carousel that shows 8 cards, there's no reason to render 400.

I covered the shortcuts I reach for first in The Liquid Patterns That Cut My Theme Build Time in Half. A lot of those patterns are fast on purpose, not just short.

The rule I follow: touch the smallest set of data that produces the right output. If the loop is reading more than the page displays, that's wasted server time, and the inspector will show it as a fat bar.

Cache the snippets that repeat the same work

The second big win is caching, and Shopify gives you more here than people realize.

When you use the render tag instead of include, the rendered snippet is isolated. It only sees the variables you pass it. That isolation is what makes caching safe, because the output depends only on the inputs, not on whatever global state happened to exist when it ran.

Shopify caches rendered fragments internally when it can, and you help it by keeping snippets pure. A snippet that takes a product and returns a card will cache better than one that reaches out to cart, customer, and three section settings at once. The more a snippet depends on, the less it can be reused.

So when I have a product card that renders 40 times on a collection page, I make it a clean snippet with one input:

{% render 'product-card', product: product %}

That's it. No globals, no surprise reads. Shopify can treat identical inputs as identical work.

For data that genuinely doesn't change per visitor, I lean on metafields instead of computing things in Liquid. If I need a product's "care instructions" or a pre-formatted spec table, I store it as a metafield and read it directly. No loop, no string building, no conditional logic on every render. I wrote up the patterns I trust for this in Shopify Metafields Done Right.

There's a quieter form of caching too: don't recompute inside the loop what you can compute once above it. If every iteration formats the same currency or looks up the same shop setting, hoist it out. Assign it to a variable before the loop and reference the variable inside. Forty lookups become one.

I also watch out for section settings read inside loops. Each section.settings.something is cheap on its own, but called 400 times it adds up. Read it once into a local variable at the top. Small change, measurable bar on the flame graph.

When I need to pass context between the storefront and checkout without recomputing it, I use cart attributes instead of rebuilding state. Background: Shopify Cart Attributes walks through the setup.

Measure again, then stop

The part people skip is measuring after the fix. I've convinced myself a change helped and then the Server-Timing number didn't move at all. Guessing feels like progress. The header doesn't care about feelings.

So after every change I reload twice and read the number again. If the slow section dropped from 310ms to 40ms, good, I move to the next bar. If it barely moved, I revert and look harder, because I misread the cause.

I keep a tiny log while I work. Just a text note with the section name, the before time, and the after time. On a recent collection template the three slowest sections started at 310ms, 180ms, and 90ms. After the loop and caching work they came in at 40ms, 55ms, and 45ms. The total Liquid time went from roughly 900ms to under 200ms. That's the whole story in five numbers, and I only trust it because I measured both ends.

Knowing when to stop matters as much as knowing where to start. Once a page renders Liquid in a couple hundred milliseconds, the next win usually isn't Liquid at all. It's image sizes, third-party scripts, or fonts. Those live in the browser, not on Shopify's server, and the Server-Timing Liquid number won't move them. Chasing Liquid further at that point is effort spent on the wrong layer.

A quick checklist I run before calling a page done:

Server-Timing Liquid under ~250ms on a warm load.
No section in the inspector over ~60ms unless it has a very good reason.
No loop reading more data than the page shows.
Repeated snippets use render, not include.

If all four pass, I close the tab. The page is fast enough, and the remaining milliseconds aren't worth the complexity of squeezing them out.

One more habit: I profile on a template I've already shipped, not just new work. Stores drift. A collection that was fast with 30 products gets slow at 300 without anyone changing a line of code. Re-profiling the big templates a couple of times a year catches that drift before a customer feels it.

Bottom Line

If a Shopify page feels slow, don't rewrite the theme. Open the Theme Inspector, read the Server-Timing header, and find the one section that's eating the budget. Nine times out of ten it's a nested loop over a collection that's grown too big, and the fix is narrowing the data or caching a clean snippet with render.

Start with the measurement. Everything else is guessing until you have the two numbers: total Liquid time and the per-section breakdown. Then fix the biggest bar, measure again, and stop when the page renders in a couple hundred milliseconds.

If you're building a store on Shopify and want the thinking behind how I keep themes in code where they can be profiled and versioned, the Claude Blueprint lays out the full approach I use. Profile first, fix the expensive thing, leave the rest alone.

This article contains affiliate links. If you sign up through them, I may earn a small commission at no extra cost to you. (Ad)

Writing Commit Messages That Double as Documentation

RAXXO Studios — Mon, 19 Oct 2026 21:40:45 +0000

A three-part commit structure (what, why, impact) answers 90% of git blame questions
Bad messages like "fix bug" cost me 20 minutes per investigation months later
The body matters more than the subject line for future archaeology
Templates and a commit hook make the good format the default

Six months after I shipped a feature, I ran git blame on a weird line of code and found a commit that said "fix stuff". That commit was mine. I had no memory of what stuff, or why. The fix was to write messages that answer the questions I'd actually ask later.

A commit message is the only documentation that sits right next to the code it describes. Most people waste it.

The Three Questions Future You Actually Asks

When I run git blame on a confusing line, I'm never asking "what does this code do". I can read the code. I'm asking why it exists.

The three questions are always the same: what changed, why it changed, and what it affected. If a commit message answers those three, I close the terminal and get back to work. If it doesn't, I go spelunking through pull requests and chat logs that may not exist anymore.

Here's a real bad one from my own history: update handler. That's the whole message. When I found it later, I had to read the diff to learn it added a timeout to an API call. The diff told me the what. It couldn't tell me the why. Was the timeout a guess? A response to a real hang? Did a specific endpoint need it? I had no idea, so I was scared to touch it.

Compare that to a message that says the timeout was added because the upstream payment API would hang for 30 seconds under load, and a 5 second timeout with a retry was faster for the user. Now I know the number isn't random. I know what breaks if I remove it. I can change it with confidence.

The "why" is the part that dies first.

Code carries its own "what". A commit carries the "what" for a day, then the diff carries it forever. But the reasoning in your head evaporates fast. You'll forget the production incident, the slow endpoint, the edge case a customer hit. Write that down while it's fresh, because the code physically cannot store it.

The impact line is the one people skip most and regret most. "This also changes the shape of the cache key, so old cached entries become stale on deploy." That sentence saves someone a confusing afternoon. I've written versions of it and been grateful to past me more times than I can count.

So the method is simple: answer those three questions in order, every time. That's all it takes.

The Structure I Actually Type

A good commit has a subject line and a body, separated by a blank line. Git treats that first line specially, so it carries weight.

The subject is 50 characters or fewer, written as a command: "Add timeout to payment handler", not "Added" or "Adding". Present tense, like you're telling the codebase what to do. It should finish the sentence "if applied, this commit will..."

Then a blank line. Then the body, wrapped around 72 characters, where the real work happens.

My body has three parts, and I don't label them. I just write paragraphs in this order:

First, what changed in plain language. Not a restatement of the diff, a summary a human can read. "The payment handler now times out after 5 seconds and retries once."

Second, why. This is the paragraph that justifies the change existing. "Under load the upstream API hangs for up to 30 seconds. Users saw a frozen checkout. A short timeout with one retry fails faster and recovers in most cases."

Third, impact and anything surprising. "Side effect: the retry doubles the request count on genuine slow responses. If the upstream recovers, this is fine. If it's truly down, the second request also fails fast."

That's it. Most of my commits are four to six lines of body. Some are one line because the change is trivial and self-explanatory ("Fix typo in error string"). The structure scales down.

The retry example above isn't hypothetical in spirit. Getting retries right is its own topic, and I covered the pattern I reuse in Retry With Backoff and Jitter. A commit that adds a retry should point at the reasoning behind the numbers, even if only in one sentence.

One thing I avoid: dumping ticket IDs as the entire message. "JIRA-4471" tells future me nothing without a login and a working link. Reference the ticket at the bottom if you must, but the message has to stand alone. Issue trackers get migrated, archived, and shut down. The git history outlives all of them.

Before and After on Real Commits

Let me show the difference with the kind of change I make all the time.

Before: migrate db. After: a subject of "Add nullable discount_code to orders" with a body explaining that the column is nullable so the migration runs without a default backfill on the existing 80,000 rows, and that application code treats null as "no code applied".

The before version is a landmine. Six months later, someone wonders why the column is nullable instead of defaulting to an empty string. The after version answers it in advance. Schema decisions are exactly the kind of thing you forget and then second-guess. If you want the deeper context on making schema changes safe, see Database Migrations I Can Roll Back at 2am.

Another one. Before: perf. After: "Switch catalog lookup to binary search" with a body noting the list is pre-sorted and has 50,000 rows, and that linear scan was showing up in profiling. Now anyone reading it knows the precondition (the list must stay sorted) and won't accidentally break it. I measured that exact tradeoff in Binary Search vs Array.includes(), and a one-line reference in the commit saves a re-benchmark.

A third. Before: fix logging. That's useless because logging changes are often subtle and load-bearing. After: "Add request ID to structured log context" with a body saying every log line in a request now carries the same ID so I can grep a full trace, and that this depends on the middleware running first.

See the pattern? The before messages are all two words and all worthless. The after messages take maybe 40 extra seconds to write and answer the question before it's asked.

I keep logs structured partly so these commit messages have something concrete to reference. The two habits feed each other, which I get into in Structured Logging I Add on Day One.

The 40 seconds feels like a tax when you're typing it. It's not. It's a loan to future you at a great interest rate. One avoided 20 minute investigation pays for 30 careful commits. I've been on both sides of that trade enough to know which I prefer.

Making the Good Format the Default

Discipline fails. I don't trust myself to write a good message every time on willpower, so I made the environment push me toward it.

The first thing is a commit template. Git lets you set one with a config pointing at a text file. Mine has comment lines reminding me of the what, why, impact order. When I run git commit without -m, my editor opens with those prompts already there. I delete the comments as I fill them in. The friction is gone because the structure is sitting in front of me.

The second thing is banning -m for anything non-trivial. The -m flag is how bad messages happen, because you're typing into a cramped shell with no room to think. Open the editor. Give yourself space. Typos in a one-line flag become "fix stuff" commits.

The third thing is squashing before I merge. My work-in-progress commits say "wip" and "oops forgot import" and I don't care, because they never reach the main branch. I squash the whole branch into one clean commit with one good message that describes the finished change. The history people read should be the story of what shipped, not the mess of how I got there.

I also use AI to draft the first pass now. I paste the diff and ask for a what/why/impact message, then I fix the "why" because the model can only guess at my reasoning. It gets the "what" right almost every time, which is the boring part anyway. If you want the setup I use for that kind of task, the Claude Blueprint walks through how I wire these helpers in.

A warning on automation: don't let a tool write the "why" for you and ship it unread. The model infers intent from the diff, and sometimes it's wrong in a way that sounds confident. A wrong "why" in the permanent history is worse than a blank one. Read what it drafts.

If you're on a solo project and think none of this matters because you're the only reader, you're the exact person it helps most. There's no teammate to ask. The git history is your only record. Past me is a stranger I can only talk to through commit messages.

Bottom Line

Start with one change today: stop using git commit -m for anything bigger than a typo. Open the editor, write three short paragraphs answering what, why, and impact, and see how it feels in a month when git blame lands on it.

If you want to go further, set a commit template so the three prompts greet you every time. That single config line did more for my history than any amount of trying to remember.

The payoff isn't visible on the day you write the message. It shows up later, when a confusing line has a clear explanation attached and you close the terminal in ten seconds instead of digging for twenty minutes. Good commits are a message to a person who's forgotten everything. That person is you.

Optimistic UI Updates That Never Lie to the User

RAXXO Studios — Sun, 18 Oct 2026 19:33:12 +0000

Optimistic UI shows the result in under 16ms, before the server replies
Keep the old value stashed so rollback is a one-line restore
Show a specific error on failure, not a silent revert
Retry with backoff beats a dead button after one failed request

A like button that waits 400ms to turn red feels broken. A like button that turns red instantly and then quietly turns gray again when the request fails is worse. I'll show you the pattern I use to get the speed without the lie.

Optimistic UI means you paint the success state before the server confirms it. The trick is handling the moment it does not confirm. That's the whole post.

Why the delay feels so bad

A network round trip from Berlin to a server in the same region is maybe 30ms to 80ms. Add the server work, the database read, the serialization, and you're often at 200ms to 500ms for a trivial write. That's under the threshold where people call something slow, but it's well over the 100ms where an interaction stops feeling instant.

So the user taps. Nothing happens for a third of a second. Then the heart fills in.

That gap trains people to tap twice. They think the first tap missed. Now you've got two requests, a race condition, and a count that reads 2 when it should read 1.

Optimistic UI closes the gap. You update the local state the instant the tap lands, which runs in the next frame (roughly 16ms at 60fps). The server call fires in the background. If it succeeds, nothing visible changes because you already showed the right thing. If it fails, you clean up.

The honest version of this has three parts and most people only build one. They build the optimistic update and skip the rollback and the error message. That's the version that lies.

Here's the shape I keep coming back to:


async function toggleLike(postId) {
  const previous = state.liked;        // stash
  state.liked = !state.liked;          // paint now
  render();

  try {
    await api.setLike(postId, state.liked);
  } catch (err) {
    state.liked = previous;            // roll back
    render();
    showError("Could not save your like. Tap to retry.");
  }
}

The stash line is the part that makes rollback cheap. You keep the old value in a const before you overwrite the state. If the request throws, you put it back. No refetch, no reload, no guessing what the value used to be.

I think about this the same way I think about database rollbacks. If you want the deeper context on undoing a change cleanly, see Database Migrations I Can Roll Back at 2am. Same instinct, different layer.

The rollback is the actual feature

Everyone shows the optimistic part in demos. The rollback is where honesty lives, and it's the part that gets cut when a deadline is near.

Think about what a user sees when the rollback is missing. They tap like and the heart fills, then they scroll away without noticing the request failed silently. They come back later and the heart is empty. Now they don't trust the button at all, because sometimes it works and sometimes it doesn't and there's no pattern they can see.

A good rollback does two things in the same tick. It restores the old value so the screen matches reality, and it tells the user why.

The restore has to be exact. If you had a count of 41 and you optimistically bumped it to 42, rolling back means going to 41, not decrementing from whatever the current value is. That matters because another update might have landed in between. The safe move is to stash the full value, not the delta.


const prevCount = state.count;
state.count = prevCount + 1;
render();

try {
  await api.increment(postId);
} catch (err) {
  state.count = prevCount;   // exact restore, not count - 1
  render();
}

For list operations the stash gets bigger. If you optimistically remove an item from a list and the delete fails, you need the item back and in the same position. I stash the item and its index before splicing, then splice it back on failure.

One thing I learned the hard way: don't animate the rollback the same way you animate the success. If deleting a row slides it out, don't slide it back in on failure. Snap it back instantly and flash the error. The slide-in reads as "here's a new thing," which confuses people. The snap reads as "that didn't happen," which is the truth.

When the error message is useless the whole pattern falls apart. "Something went wrong" tells the user nothing they can act on. "Could not save, check your connection" at least points somewhere. Structured logs on the server side tell you which failures are real. I set that up on day one, which I covered in Structured Logging I Add on Day One of Every Project.

Retry so one dropped packet doesn't kill the action

A single failed request is often not a real failure. It's a flaky connection, a cold server, a dropped packet on a subway WiFi. If you roll back and give up, you've punished the user for the network's problem.

So I retry before I roll back. Not forever, and not instantly.

The naive retry loops immediately and hammers a server that might already be struggling. If 500 clients all retry at the same millisecond, you get a thundering herd and the server that was slow becomes a server that's down. The fix is backoff with jitter: wait a bit longer each attempt, and add randomness so the retries spread out instead of landing in sync.


async function withRetry(fn, attempts = 3) {
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (err) {
      if (i === attempts - 1) throw err;
      const base = 200 * 2 ** i;          // 200, 400, 800
      const jitter = Math.random() * 100; // spread them out
      await new Promise(r => setTimeout(r, base + jitter));
    }
  }
}

Wrap the API call in that and the optimistic update stays painted the whole time. The user never sees the retries. They see the heart turn red, and it stays red because the second attempt landed. Only after three tries fail do you roll back and show the error.

I use this exact helper in a lot of places. The full version with the reasoning behind the numbers is in Retry With Backoff and Jitter: The Version I Copy Everywhere.

One caution: only retry things that are safe to repeat. A like toggle is idempotent if you send the target state (liked: true) instead of a command (toggle). Sending the target state means two retries that both land just set it to true twice, which is fine. Sending "toggle" twice flips it back, which is a bug. Design the API so retries can't hurt you, and the whole pattern gets safer.

And give people a manual retry too. After the automatic attempts fail, the error message itself should be the retry button. "Tap to retry" that re-runs the whole optimistic flow. That turns a dead end into a second chance without a page reload.

Where optimistic UI is a bad idea

Speed is not always worth the risk of showing something false. Some actions should wait for the server, and pretending otherwise erodes trust faster than any spinner.

Money is the obvious one. Never show "payment complete" optimistically. If the charge fails after you've shown success, you've told someone they paid when they didn't. Wait for the real confirmation. A 600ms spinner on a checkout button is fine because people expect money to take a moment.

Anything irreversible is the same category. Deleting an account, sending a message that can't be unsent, publishing something public. If rollback can't fully undo the visible effect, don't do the optimistic update.

The sweet spot is small, reversible, low-stakes actions. Likes, bookmarks, reordering a list, toggling a setting, adding to a cart. If it fails and rolls back, the user shrugs and taps again. Nobody's day is ruined.

There's also a counting problem to watch. If you optimistically update a number that other users also change, your local view can drift. Say a post has 100 likes, you add one and show 101, but three other people liked it in the same second so the real count is 104. Your optimistic 101 is now wrong in a way rollback won't catch, because the request succeeded.

I handle this by treating the server response as the source of truth when it arrives. The optimistic value is a guess. When the real count comes back, I replace the guess with it, even on success. The user sees 101 for a moment, then it snaps to 104, which reads as "oh, other people liked it too" rather than a bug.

For reads rather than writes, the performance questions are different. If your list is huge and the bottleneck is rendering, not the network, optimistic UI won't help. I measured that tradeoff in I Measured content-visibility: auto on 3,000 Cards, and the fix there is rendering strategy, not request timing.

Know which problem you have before you reach for this pattern. Optimistic UI fixes perceived latency on writes. It does nothing for a slow render.

Bottom Line

Build all three parts or skip the pattern. The optimistic paint is the easy 20 percent. The stash-and-restore rollback and the specific error message are the 80 percent that keeps the screen honest when the network drops a packet on a train.

My default: optimistic for small reversible writes, retry three times with backoff before giving up, and always let the server's real response overwrite my guess. For money and anything irreversible, I wait for confirmation and eat the spinner.

If you're wiring this into a project from scratch and want a setup that's structured for a solo build, Claude Blueprint is how I lay the groundwork before I write a single component.

Start with one button. Add the stash, the rollback, the error. Get that one honest, then copy the shape everywhere else.

AVIF, WebP or JPEG: Picking an Image Format in 2026

RAXXO Studios — Sat, 17 Oct 2026 19:38:18 +0000

AVIF cuts photo file size 30-50% below JPEG but encodes slower
WebP is the safe middle ground with 97%+ browser support
JPEG stays as the final fallback so nobody gets a broken image
The picture element tries each format top to bottom automatically

I shipped a product page last month with a hero photo that weighed 1.4MB as JPEG. Re-encoded as AVIF it dropped to 320KB with no visible loss. That's the whole reason this choice matters, and in 2026 you don't have to pick just one.

Here's how I decide which format to serve, and how I stack all three so a visitor on any browser still sees the picture.

What Each Format Is Actually Good At

JPEG is 30 years old and it still works everywhere. Every browser, every email client, every ancient Android phone. It handles photos well. It falls apart on sharp edges, text, and flat color, where you get those grey smudges around lines. It can't do transparency. For a photograph where support matters more than bytes, it's still fine.

WebP is the one I reach for by default. It does both lossy and lossless, it supports transparency, and it animates. On a typical product photo it lands 25-35% smaller than JPEG at the same visual quality. The encode is fast. The support is basically universal now.

AVIF is the heavy hitter. Based on the AV1 video codec, it crushes file sizes harder than anything else I've tested. That 1.4MB JPEG becoming 320KB wasn't a fluke, 30-50% below JPEG is the normal result. It handles transparency, wide color gamut, and HDR. The catch is encode time. AVIF is slow to compress, sometimes 10-20x slower than WebP for the same image.

So the rough rule I use:

Photos where every byte counts: AVIF first.

UI assets, icons, screenshots with text: WebP, because the encode is quick and the quality holds on sharp edges.

Anything that has to display on hardware I can't predict: keep a JPEG around.

One thing people forget is that quality settings aren't comparable across formats. AVIF quality 50 is not WebP quality 50. I tune each one by eye, or by target file size, not by copying a number across. For a 1600px-wide hero I usually land around AVIF quality 55, WebP quality 78, JPEG quality 82. Those numbers drift per image, but they're my starting point.

Browser Support in 2026 and Why It's Not a Blocker

The support question used to end these debates. It doesn't anymore.

WebP is supported in every current browser and has been for years. If you're only serving WebP with a JPEG fallback, you're covering everyone who's touched a browser update since roughly 2020. No caveats.

AVIF is the newer one, and it's the reason people still hesitate. But Chrome, Firefox, Edge, Safari, and the mobile versions of all of them decode AVIF now. The gaps are old installs and a few embedded webviews. That's a small slice, and it's shrinking every month.

The reason none of this stops me is the fallback chain. I don't have to bet on AVIF support. I serve AVIF to browsers that take it and quietly drop down to WebP, then JPEG, for everyone else. The browser picks the first format it understands. No feature detection in JavaScript, no user-agent sniffing, no broken image icon.

That's the part worth sitting with. You can adopt the newest, smallest format with zero downside, because the fallback is built into HTML itself. The worst case for an old browser is that it gets the JPEG it would have gotten anyway. The best case for a modern browser is a file less than a quarter the size.

I treat performance work the same way I treat reliability work: assume something will fail and make the failure boring. If you want the same mindset applied to retries, Retry With Backoff and Jitter walks through the pattern I copy into every project.

The only real cost of adding AVIF is the encode step at build time, and that's a machine problem, not a user problem. Which brings up the trade I actually think about.

Encode Cost Versus File Size

Smaller files are not free. Somebody's CPU paid for them.

AVIF's compression comes from doing a lot of work up front. On my build machine, encoding a single 2000px photo to AVIF at a good quality setting takes a few seconds. WebP does the same image in a fraction of that. JPEG is near instant. Multiply by a catalog of a few hundred product shots and the AVIF step is suddenly the slowest thing in the build.

I handle this with a cache. I hash the source image plus the encode settings, and if nothing changed I reuse the output. So AVIF only pays its slow encode once per image, not once per build. After the first run, rebuilds skip anything untouched. This is the same caching instinct I use for catalog lookups, which I benchmarked in Binary Search vs Array.includes().

The numbers that make the slow encode worth it: a 10-image gallery at 1.4MB each is 14MB of JPEG. The same gallery in AVIF can come in under 4MB. That's the difference between a page that loads instantly on mobile and one where images pop in a second late while someone's already scrolling past.

I also don't encode every size for every format. I pick two or three widths (say 640, 1280, 1920), and generate AVIF and WebP for each, plus one JPEG fallback per width. That's a manageable fan-out. Going wider than three sizes rarely earns its keep for the kind of pages I build.

If you're generating or upscaling source art before you compress it, the encode step runs on whatever you export. I run a lot of my source images through Magnific for upscaling first, then compress the result into the format stack. Clean source in, small files out.

One honest caveat: AVIF can look worse than WebP at very low file sizes on images with fine grain or film noise. It smooths detail it thinks is unimportant. For a product on a plain background that's invisible. For textured photography, check it with your own eyes before trusting the byte count.

The Fallback Chain I Actually Ship

This is the whole thing in one HTML element. The picture element lets you list sources in order, and the browser uses the first one it supports.


<picture>
  <source srcset="hero.avif" type="image/avif">
  <source srcset="hero.webp" type="image/webp">
  <img src="hero.jpg" alt="Product hero shot" width="1280" height="720">
</picture>

The browser reads top to bottom. If it's AVIF-capable, it takes the first line and stops. If there's no AVIF support but WebP works, it uses the second line instead. Nothing modern at all? It falls through to the plain img, which every browser understands. That img is not optional. It's the thing that guarantees nobody sees a broken image.

A few details I never skip.

Always set width and height on the img. This reserves the space before the image loads so the page doesn't jump around. Layout shift is one of the easiest performance wins and most people leave it on the table.

Always write a real alt. The fallback chain protects the format, the alt protects the meaning when the image itself fails.

For responsive sizes, each source gets its own srcset with the width descriptors, and a sizes attribute so the browser knows how wide the image renders. That gets verbose fast, which is why I generate the whole block from a template rather than writing it by hand. I feed the image name and dimensions in, and the markup comes out with all three formats and all my widths wired up.

I keep that generation logic in the same place as the rest of my asset pipeline, with structured logs so I can see which images got re-encoded and which came from cache. If that sounds useful, Structured Logging I Add on Day One is how I set that up.

The result is one source of truth. I drop in a JPEG or PNG, the build produces the AVIF and WebP variants, caches them, and writes the picture markup. I never touch the fallback chain by hand, so I never get it wrong.

Bottom Line

If you do nothing else, serve WebP with a JPEG fallback. That's a 25-35% size cut on your photos with support you don't have to think about, and it's maybe an hour of pipeline work.

If you want the bigger drop and you've got a build step that can cache, add AVIF as the top of the chain. The picture element means there's no risk: old browsers get the JPEG they'd have gotten anyway, modern ones get a file a third of the size. Just watch textured images by eye, and cache the slow encode so it only runs once.

I'd start with the three-format stack on your heaviest page, measure the load, and roll it out from there. The pattern is the same everywhere, which is the point. I document how I wire these build-time steps into a repeatable setup in the Claude Blueprint if you want the fuller picture of how my pipeline fits together.

Pick the format per use, keep the fallback, and let the browser do the choosing.

This article contains affiliate links. If you sign up through them, I may earn a small commission at no extra cost to you. (Ad)

Database Migrations I Can Roll Back at 2am

RAXXO Studios — Fri, 16 Oct 2026 20:01:58 +0000

Every schema change ships with a down step, tested before deploy
Expand and contract splits one risky change into four safe ones
Deploy code before the destructive migration, never the reverse
A dropped column at 2am can't be undone, so never drop first

The worst database mistake I ever made was a migration with no down step, run at 2am, that dropped a column before I had a backup. I spent three hours reconstructing data from logs. Now every schema change I ship can roll back cleanly, and I've never had that panic again.

Here's how I structure migrations so the rollback is boring.

Every Change Ships With Its Down Step

A migration has two halves. The up step moves the schema forward. The down step moves it back. Most ORM tools generate both for you, and most people delete or ignore the down step because it feels like extra work.

I don't. If I can't write the down step, I don't ship the up step.

The reason is simple. At 2am, half asleep, with an error spiking, I don't want to be writing SQL. I want to run one command that puts the schema back exactly where it was five minutes ago. If I planned the reverse ahead of time, that command already exists.

Writing the down step also forces me to think about whether the change is reversible at all. Adding a column? Easy to reverse, just drop it. Renaming a column? That's two operations pretending to be one, and the naive version loses data on rollback. Dropping a column? There is no honest down step, because the data is gone. The moment I write "down: re-add the column" I realize the data to fill it doesn't exist anymore.

That realization is the whole point. The down step is a test of whether the change is safe, and I'd rather fail that test at my desk than in production.

I test the down step before I deploy. I run up, then immediately run down, then up again. If the schema doesn't return to a working state after that cycle, the migration isn't ready. This catches things like a foreign key that gets dropped on the way down but not recreated, or an index that survives a rollback and collides with the next up run.

The same discipline shows up in how I handle undo across my tools. If you want the deeper context on reversible operations, see The Undo Button Every RAXXO Tool Ships With. The database version is just the same idea with foreign keys attached.

Expand And Contract: One Change, Four Steps

The pattern that saved me is expand and contract. Instead of changing a column in place, I split the change into stages that are each safe on their own.

Say I want to rename user_name to username. The dangerous way is one migration that renames the column. If anything goes wrong mid-deploy, old code looks for user_name and new code looks for username, and one of them is always wrong.

The expand and contract way takes four steps across two or more deploys.

First, expand. I add the new username column alongside the old one. Nothing reads from it yet. This migration is pure addition, so its down step is a clean drop with zero data loss.

Second, backfill. I copy data from user_name into username, and I make the application write to both columns on every update. Now the two columns stay in sync. Old code reads the old column, new code can start reading the new one.

Third, migrate reads. I deploy code that reads from username. The old column still exists and still gets written, so if I need to roll this deploy back, nothing breaks.

Fourth, contract. Once I'm confident the new column is correct and nothing reads the old one, I drop user_name in a separate migration, days later.

Each step is reversible until the very last one. The only irreversible operation, the drop, happens when I'm calm and certain, not in the middle of a deploy. For large tables the backfill runs in batches so I don't lock a 50,000-row table in one transaction. I covered batching big scans in more depth at Binary Search vs Array.includes() on a 50,000-Row Catalog, and the same instinct applies here: never touch every row at once if you can help it.

This feels slower. It is slower. Four deploys instead of one. But I've never corrupted data with this pattern, and the four small steps each take two minutes while the one big step takes three hours when it goes wrong.

The Order Of Deploy And Migrate Matters

The single rule that prevents most 2am incidents: additive migrations run before the deploy, destructive migrations run after.

Think about what happens during a deploy. There's a window where old code and new code both exist. Instances restart one at a time. For thirty seconds, maybe two minutes, the database serves both versions of your application at once.

If I add a column before deploying the code that uses it, both old and new code are fine. Old code ignores the column. New code finds it waiting. The additive migration ran first, so the schema is always ahead of the code.

If I drop a column during that window, old code that still expects it crashes. So drops wait until every instance runs the new code. Destructive migration runs last, after the deploy fully settles.

The order flips depending on direction:

For adding things, migrate then deploy. The schema leads.

For removing things, deploy then migrate. The code leads.

Rollback follows the same logic in reverse. If I roll back a deploy, the old code comes back, and I need the old schema to still support it. That's exactly why the destructive step waited. The column is still there, so the rolled-back code finds everything it expects. No data lost, because I never dropped anything the old code depended on.

This is the piece people skip, and it's the piece that turns a routine rollback into a data-loss event. A rollback should never require a down migration that recreates data. If your rollback plan is "run the down step to re-add the dropped column," you've already lost, because the data to fill it is gone.

I keep a one-line rule in my deploy notes: a rollback must work with the schema that's live right now, without running any down migration at all. If that's not true, the migration order is wrong. For how I watch the deploy window itself, Structured Logging I Add on Day One of Every Project covers the tracing I lean on.

Failures That Need Retries, Not Rollbacks

Not every migration problem is a rollback problem. Some are just a flaky connection, and rolling back is the wrong response.

A long backfill on a big table can fail halfway because the database connection drops, or a lock times out, or a replica falls behind. If I panic and roll back, I've thrown away the half that worked. The better move is making the migration safe to re-run.

I write backfills to be idempotent. Instead of "copy every row," the query is "copy every row where the target is still null." Run it once, it fills 20,000 rows. The connection drops. Run it again, it fills the remaining 30,000 and skips the ones already done. No duplicates, no corruption, no need to start over.

For the actual retry logic around a flaky migration runner, I use the same backoff I use everywhere. If you want the exact code, Retry With Backoff and Jitter is the version I copy into every project. A backfill that hits a transient lock should wait and retry, not fail the whole deploy.

The distinction I hold onto: a schema change that's structurally wrong gets a rollback. A schema change that's structurally fine but hit a network hiccup gets a retry. Mixing those up is how people make a small problem bigger.

I also set a statement timeout on every migration. Without one, a migration that grabs a lock can block every query on the table and bring the whole app down while it waits. With a timeout, the migration fails fast, I see the lock contention, and I run it again during a quieter window. A failed migration that failed in two seconds is a non-event. A migration that hung for ten minutes holding a lock is an outage.

The running database here is Postgres behind a Shopify storefront and a few side services, so I care a lot about not locking tables that serve live traffic. Idempotent, timeout-bounded, re-runnable. That trio keeps a shaky migration from turning into a decision I have to make at 2am.

Bottom Line

If you only change one thing, make it this: write the down step before you write the up step, and test the full up-down-up cycle at your desk. That one habit catches the irreversible changes before they reach production.

Then layer in the order rule. Additive changes migrate before deploy, destructive changes migrate after, and drops wait days behind their own separate migration. A rollback should work against the live schema with no down migration required. If it doesn't, you've ordered something wrong.

Expand and contract feels like overkill until the first time it saves you from a 2am data loss. After that it's just how you rename a column.

I keep these rules in the same operations playbook I build every project from. If you want the full setup I start with, Claude Blueprint walks through how I wire logging, retries, and migrations together from day one. Start there, steal what's useful, and make your next rollback boring.

This article contains affiliate links. If you sign up through them, I may earn a small commission at no extra cost to you. (Ad)

How I Write Alt Text That Helps Screen Readers and Search

RAXXO Studios — Thu, 15 Oct 2026 20:29:14 +0000

Decorative images get empty alt (alt=""), never missing alt
Aim for 8 to 15 words, one sentence, no "image of"
Product alt names the thing plus one distinguishing detail
Charts get the takeaway, not the axis labels

Alt text is the one accessibility task that pays off twice. A screen reader reads it out loud to someone who can't see the image, and a search engine reads it to understand what the page is about. Get it right once and both audiences win.

Most alt text I see on the web is either missing entirely or stuffed with keywords that help nobody.

Here's how I decide what to write and when to write nothing at all.

When An Image Needs Alt Text And When It Should Be Empty

The first decision isn't what to write. It's whether to write anything.

An image needs real alt text when it carries information the surrounding text doesn't. A product photo, a diagram, a screenshot of a result, a chart with numbers in it. If the image went missing and the page got worse, it needs a description.

An image should have empty alt text when it's decorative. A background texture, a divider line, a stock photo of a laptop next to an article about laptops. These add nothing a screen reader user needs. For those I write alt="", an empty but present attribute.

That empty string matters.

There's a real difference between alt="" and no alt attribute at all. Empty alt tells the screen reader "skip this on purpose." A missing attribute makes the screen reader fall back to reading the file name out loud, so the user hears "IMG underscore 4471 dot jpg" in the middle of a sentence. That's the worst outcome and it happens constantly.

So my rule is simple. Every image gets an alt attribute, always. The only question is whether it's filled or empty.

A quick test I run in my head: if I read the page out loud to a friend over the phone, would I describe this image? If yes, write it. If I'd skip it because the text already covered the point, leave it empty.

Icons are the tricky middle case. An icon that's purely visual next to a text label gets empty alt, because the label already says "Settings." An icon that stands alone as a button, like a magnifying glass with no word next to it, needs alt text that says what it does: "Search."

One more case worth naming. If an image is also a link, the alt text describes where the link goes, not what the picture looks like. A logo that links home gets alt="RAXXO home", not alt="orange logo".

I apply this same "empty on purpose" discipline to other invisible states in my tools. The idea of a deliberate default shows up in The Undo Button Every RAXXO Tool Ships With too.

How Long Alt Text Should Be

Short. Shorter than you think.

My target is 8 to 15 words. One sentence, no period needed, no padding. A screen reader user hears this text read out loud, and nobody wants to sit through a paragraph describing a thumbnail.

Here's the trap. People treat alt text as a place to write everything they know about the image. That turns a 10-word description into a 60-word essay the listener can't skip past easily. If the image genuinely needs a long explanation, like a complex infographic, the right move is a short alt plus a longer description in the visible page text or a caption.

Skip the phrases "image of" and "photo of." The screen reader already announces that it's an image before reading your text. So "image of a blue mug" gets read as "image, image of a blue mug." You said image twice. Just write "blue ceramic mug on a wooden desk."

Watch for keyword stuffing.

I've seen alt text like "best coffee mug buy coffee mug cheap coffee mug online." A search engine treats that as spam, and a human listener hears gibberish. One honest description beats five repeated keywords every time.

Punctuation matters less than rhythm. I write alt text the way I'd say it. "Dashboard showing 1,200 orders in the last 30 days" reads cleanly out loud. "Dashboard; orders; 30-day view; metrics" does not.

When I generate or upscale images for product pages, I write the alt text in the same pass, while I still remember what the image was meant to show. If I'm using something like Magnific to clean up a product render, the description goes in right then, not three weeks later when I've forgotten which variant this was.

A good length check: read your alt text out loud at normal speed. If you run out of breath or lose the thread before the end, cut it.

Most of my best alt text lands around 10 words and says exactly one thing clearly.

I also keep a small list of alt text patterns the way I keep naming patterns. Consistency helps, and I wrote about that habit in The Command Naming Convention Every RAXXO Tool Follows.

Describing A Product Image So Both Audiences Get The Point

Product images are where good alt text earns its keep. A shopper using a screen reader is deciding whether to buy, and a search engine is deciding whether to rank your product for the right query. Both need the same core facts.

My formula: name the product, then add the one detail that distinguishes this photo from the other photos of the same product.

So for a listing with five images of the same jacket, I don't write "green jacket" five times. I write "green waxed jacket, front view," then "green waxed jacket, inside lining," then "green waxed jacket worn open over a sweater." Each one adds something. A sighted shopper flips through photos to learn more; the alt text should give a screen reader user that same progression.

Color, material, and the angle or context are usually the facts that matter most. For a mug: "matte black mug, 350ml, held in one hand for scale." That last part tells someone the size better than a number alone.

Avoid describing emotion or vibe. "Cozy inviting lifestyle shot" means nothing to a listener trying to decide on a purchase. Say what's actually pictured: "mug steaming on a windowsill next to an open book."

Price and stock go in the page text, not the alt. Those change, and alt text shouldn't carry data that goes stale.

If you run your store on Shopify, the alt field sits right in the media editor for each image, and the theme usually outputs it correctly. The platform handles the plumbing. The words are still your job, and the default is almost always blank.

One thing I watch: variant images.

If a product has 12 color variants and each has its own photo, generic alt like "product image" wastes all of them. The color name is the single most useful word you can add, so "rust orange variant, folded flat" does real work for search and for a listener comparing options.

When I repurpose product shots into short social posts, the alt text travels with them. I described that whole pipeline in How I Turn One Long Article Into a Week of Short Posts, and keeping alt text attached across platforms saves rewriting it later.

Describing A Chart Or Diagram Without Listing Every Axis

Charts break the "describe what you see" rule, and this is the part most people get wrong.

A sighted reader doesn't read a chart pixel by pixel. They glance at it and absorb the takeaway: sales went up, this bar is the tallest, the trend is flat. So the alt text should deliver that takeaway, not recite the axis labels and every data point.

Bad alt for a bar chart: "Bar chart with x-axis labeled months January through June and y-axis labeled sales from 0 to 500." That describes the furniture, not the story. A listener still has no idea what the chart says.

Good alt: "Bar chart showing sales rising from 120 in January to 480 in June." Now they know the point in one sentence.

For a chart with a clear single message, lead with the message. "Monthly sales nearly doubled over the first half of the year." That's often better than any number because it's the reason the chart is on the page.

When the chart genuinely holds data a listener might need, I give short alt plus a real alternative. A caption with the key figures, or better, the underlying numbers in an actual table on the page. A data table is readable by screen readers cell by cell, so complex data belongs there, not crammed into alt text.

Pie charts: name the biggest slice and roughly how dominant it is. "Pie chart, mobile traffic makes up about 70 percent, desktop the rest." Nobody needs all six slivers read out.

Line charts: direction and shape.

"Line chart trending steadily upward, with a dip around April." The dip is worth mentioning because a sighted reader would notice it instantly.

The same logic applies to screenshots of data. If I post a screenshot of a dashboard, the alt text says the number that matters, like "dashboard showing 3,400 downloads this week," not "screenshot of a dashboard interface with sidebar and charts."

Audio content gets the same respect. When I describe a chart in a voiceover using ElevenLabs, I lead with the takeaway there too, because a listener's attention works the same way whether it's a screen reader or a narrator.

Bottom Line

Write an alt attribute on every image, then decide if it's filled or empty. Decorative images get alt="". Everything that carries meaning gets one short sentence, 8 to 15 words, that says the thing the picture is actually there to say.

For products, name it plus the one detail this photo adds. For charts, give the takeaway, not the axis labels, and push complex data into a real table.

If you want a repeatable way to bake this into your whole publishing setup, start with the Claude Blueprint. It's how I keep small habits like alt text from slipping through the cracks when I'm moving fast.

The best part is that none of this is extra work once it's a reflex. You write the words while the image is fresh, and a screen reader user and a search engine both thank you for it. Start with your next upload.

This article contains affiliate links. If you sign up through them, I may earn a small commission at no extra cost to you. (Ad)

Retry With Backoff and Jitter: The Version I Copy Everywhere

RAXXO Studios — Wed, 14 Oct 2026 20:53:29 +0000

Naive retries hammer a recovering server and turn blips into outages
Full jitter spreads retries so clients stop firing in sync
Retry 429 and 503, never 400 or 401, and respect idempotency
A 20-line function I paste into every project, copy it

A single failed API call shouldn't take down your backend. But the naive retry loop most people write does exactly that, because it waits the same amount of time on every client and fires them all back at once. Here's the version I copy into every project instead.

Why naive retries make outages worse

Picture a service that handles a thousand requests a second. Something hiccups for two seconds. A load balancer blips, a database connection pool fills up, whatever. During those two seconds, maybe two thousand requests fail.

Now every one of those clients retries. If they all retry immediately, you get two thousand extra requests the instant the service comes back. On top of the normal thousand per second. The service that was already struggling now gets hit with triple the load at the worst possible moment.

That's a retry storm. The retries cause the outage to keep going.

I've seen this pattern play out with fixed-delay retries too. "Wait one second, then try again" sounds safe. But if all your clients failed at the same moment, they all wait one second, and they all come back at the same moment. You've just moved the stampede one second into the future. You didn't spread it out.

The naive loop looks reasonable on paper:


for (let i = 0; i < 5; i++) {
  try {
    return await call();
  } catch (e) {
    await sleep(1000);
  }
}

Five tries, one second apart. Fine for one client sitting alone. Terrible when ten thousand clients run the identical loop and fail together.

The fix has two parts. First, back off more each time so you're not pounding a recovering service. Second, add randomness so clients spread out instead of syncing up. The first part is exponential backoff. The second part is jitter. People remember the first and forget the second, and the second is the one that actually saves you.

Backoff alone still clusters. If everyone uses delay = base * 2^attempt, then everyone's third retry lands at the same tick. You need the random offset to break the alignment. Think of it as politeness from each client toward a server that's having a bad day. If you want to see the failures clearly while this is happening, you'll want logging in place first. I covered this in more depth at Structured Logging I Add on Day One of Every Project.

Full jitter, and why I don't use the other kinds

There are a few flavors of jitter. I'll save you the comparison I did and tell you the winner: full jitter.

With full jitter, you compute the exponential ceiling, then pick a random delay between zero and that ceiling. So on attempt three with a 200ms base, the ceiling might be 1600ms, and you sleep somewhere between 0 and 1600ms. Every client picks its own number. They scatter across the whole window instead of bunching at the top.

The formula is short:


cap = min(maxDelay, base * 2^attempt)
delay = random(0, cap)

Compare that to "equal jitter," where you sleep half the ceiling plus a random half. That still keeps a floor under every client, so they're less spread out. Full jitter uses the whole range and spreads the hardest.

The counterintuitive part: picking a delay that can be as low as zero feels wrong. Won't some clients retry almost instantly? Yes, a few will. But only a few, because the random pick is uniform across the window. The rest land all over the place. The total load at any single instant stays low, which is the entire point.

I cap the maximum delay too. Without a cap, 2^attempt grows fast, and by attempt ten you're waiting 200 seconds. A 30-second cap is usually sensible. I also cap the number of attempts, because retrying forever just hides a real problem. Four or five attempts is my default.

One more thing: measure before you tune these numbers. Base delay, cap, and attempt count all interact. The habit of counting actual calls instead of guessing is the same one I used in Debounce vs Throttle: I Counted Every Call. Don't pick 2^attempt because it's traditional. Pick it because you watched the timing and it spread your load the way you needed.

If your clients are all on cron jobs that fire on the minute, jitter matters even more. Without it, every scheduled job hits your API on the exact same second, every minute, forever.

Which errors deserve a retry, and which never do

Retrying the wrong error is worse than not retrying at all. You burn attempts, you add latency, and sometimes you do real damage.

Retry these: HTTP 429 (too many requests), 503 (service unavailable), 502 and 504 (gateway errors), and network-level failures like a connection reset or a timeout. These are temporary. The server is busy or briefly unreachable, and a later attempt has a real chance of working.

Never retry these: 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), and 422 (unprocessable). These are your fault, not a transient blip. Your payload is malformed, your token is wrong, or the thing doesn't exist. Retrying sends the identical broken request again and gets the identical rejection. You just wasted five round trips to confirm what the first one told you.

For 429 specifically, check for a Retry-After header. If the server tells you exactly when to come back, use that number instead of your computed backoff. The server knows better than your formula does.

Then there's idempotency, which is the part people skip and regret. A GET is safe to retry; you're just reading. A PUT or DELETE is usually safe because repeating it lands you in the same state. A POST is the dangerous one. If you POST "create order," time out before the response, and retry, you might create two orders. The first one may have succeeded and you never saw the reply.

So for non-idempotent writes, either don't retry, or send an idempotency key so the server deduplicates. Most payment and order APIs support a key header exactly for this. Set it once per logical operation and reuse it across retries.

I keep a tiny classifier function that answers one question: is this error retryable? It checks the status code against the retry set, checks for network error types, and returns a boolean. Keeping that logic in one place means I never second-guess it at the call site.

Timeouts are the subtle case. A timeout on a read is retryable. A timeout on a write might mean the write already happened. Treat write timeouts with the same caution as a POST. If you want to understand the failure modes that hide behind a simple-looking call, I Found the Exact Recursion Depth That Crashes Node is a good companion read.

The function I actually paste

Here's the whole thing. It's short on purpose. I'd rather read twenty lines than trust a dependency for this.


const RETRYABLE = new Set([429, 502, 503, 504]);

function sleep(ms) {
  return new Promise((r) => setTimeout(r, ms));
}

async function retry(fn, opts = {}) {
  const base = opts.base ?? 200;
  const cap = opts.cap ?? 30000;
  const max = opts.max ?? 5;

  let attempt = 0;
  while (true) {
    try {
      return await fn();
    } catch (err) {
      const status = err.status ?? err.response?.status;
      const retryable =
        RETRYABLE.has(status) || err.code === "ECONNRESET";

      if (!retryable || attempt >= max) throw err;

      const ceiling = Math.min(cap, base * 2 ** attempt);
      const delay = Math.floor(Math.random() * ceiling);
      await sleep(delay);
      attempt++;
    }
  }
}

That's it. Base delay, a cap, a max attempt count, full jitter on every wait. You call it like await retry(() => fetch(url)) and it handles the rest.

A few notes on using it. Pass your own retryable check when you need one; the default set covers most HTTP cases, but a database driver throws different error shapes. I usually add an onRetry callback so I can log each attempt with the delay it chose, which makes retry storms obvious in the logs when they happen.

For a Retry-After header, I read it before computing the jitter and clamp my delay to at least that value. The server's instruction wins.

Don't wrap this around non-idempotent writes without an idempotency key. The function doesn't know your POST is dangerous. That judgment stays with you at the call site.

I keep the retryable set small and explicit on purpose. It's tempting to retry on any 5xx, but a 500 is often a genuine bug on the server that won't fix itself in 400ms. I'd rather fail fast and see it than mask it behind four quiet retries.

This same instinct (small, boring, reusable building blocks I trust) is how I build everything at the studio. The full approach is in the Claude Blueprint. It's the same idea applied to a whole workflow instead of one function.

Bottom Line

Copy the function above into your next project and tune three numbers: base delay, cap, and max attempts. Start with 200ms, 30 seconds, five tries, then watch your logs and adjust once you see real failures.

The single change that matters most is the jitter line. Math.random() * ceiling instead of a fixed wait is what stops your clients from stampeding a server that's already down. Everything else is detail.

And before you wrap any write in a retry, ask whether running it twice is safe. If it isn't, add an idempotency key or leave the retry off. A missed error you can see beats a duplicate order you can't.

If you want the broader way I think about resilient, boring code that keeps working when I'm not looking at it, the Claude Blueprint walks through the whole setup. Grab the function, ship it today, and your next outage stays a blip instead of becoming the story.

Focus States That Survive a Redesign: A Keyboard-First Checklist

RAXXO Studios — Tue, 13 Oct 2026 21:56:29 +0000

Redesigns silently break focus states; I run a 6-point check before every ship
Replace :focus with :focus-visible so mouse clicks stay quiet, keyboards stay loud
A 3:1 contrast outline against both themes is the bar I hold
Tab the whole page once with the mouse unplugged, no exceptions

A visual refresh almost always eats the keyboard experience. The design looks cleaner, the colors are nicer, and somewhere in the diff the focus outline quietly vanished. I've shipped enough redesigns to treat this as a certainty, not a risk, so I built a short checklist I run every single time.

Here's the whole thing. You can run it on your own site in about twenty minutes.

Why Redesigns Eat Focus States First

Focus is invisible until you need it. That's the core problem. When I'm staring at a new layout in the browser, I'm clicking with a mouse, and a mouse never shows me a focus ring. So the one thing a keyboard user depends on is the one thing I'm least likely to notice is gone.

The usual culprit is a CSS reset. A designer drops in outline: none to kill the default browser ring because it "looks ugly," and then forgets to add anything back. Now every button, link and input is a dead end for anyone using Tab.

The second culprit is a component library swap. You move from one set of styled components to another, and the new ones ship with their own focus behavior. Maybe it's there, maybe it's a 1px gray line that disappears against a gray background. You inherited someone else's decision and never checked it.

The third is theme work. You add a dark mode, the outline color was hardcoded to a dark value, and now it's invisible on the dark canvas. The light theme is fine. The dark one is a black box, literally.

I treat the redesign diff as guilty until proven innocent. Any time I touch global styles, swap a component, or add a theme, I assume focus is broken and I go check. This is the same defensive habit behind The Undo Button Every RAXXO Tool Ships With: assume the scary path is the one nobody tests, then test it on purpose.

One more thing worth saying plainly. Keyboard users aren't a tiny edge group. Power users navigate with Tab because it's faster. Screen reader users depend on it. People with motor conditions that make a mouse painful rely on it entirely. When the focus ring dies, all of them lose their place on the page at once.

Swap :focus For :focus-visible

The single highest-value change I make is replacing :focus with :focus-visible.

Old focus styling had an annoying tradeoff. If you styled :focus to be loud enough for keyboard users, mouse users saw a big ring every time they clicked a button, which looked wrong. So people removed it, and both groups lost out.

:focus-visible solves this. The browser decides. Click a button with a mouse, no ring. Tab to it with a keyboard, loud ring. Same CSS, different behavior based on how the element got focus.

My baseline rule looks like this:


:focus-visible {
  outline: 2px solid currentColor;
  outline-offset: 2px;
}
:focus:not(:focus-visible) {
  outline: none;
}

The outline-offset matters more than people expect. A ring pressed flat against the element edge reads as a border, not a focus state. Two pixels of gap makes it obvious the element is selected, and it keeps the ring from clipping on rounded corners.

I use outline, not box-shadow, for the ring. An outline doesn't trigger layout shift and it doesn't get clipped by overflow: hidden on a parent. box-shadow focus rings vanish inside scroll containers all the time, and you won't catch it until something scrolls.

There's one trap with outline: none as a reset. Never, ever apply it globally without a :focus-visible style to replace it. If you write *:focus { outline: none } and nothing else, you've deleted keyboard navigation for the entire site in one line.

I've seen this ship in production more than once.

Test the swap by unplugging your mouse, or just setting it aside, and pressing Tab. Every interactive element should light up as you move. If one doesn't, it's either not actually focusable (a div pretending to be a button) or your ring style doesn't apply to it.

This is the kind of small, boring default I bake into the starting point so I never have to think about it again, same idea as The Starter Template Every RAXXO Tool Begins From. Set it once, inherit it everywhere.

Contrast The Ring Against Both Themes

A focus ring that exists but can't be seen is the same as no ring. The number I hold it to is a 3:1 contrast ratio between the outline color and whatever's directly behind it.

Three to one is the threshold for non-text UI elements in the accessibility guidelines. A focus indicator counts. So I check the ring against the element's own background and against the page background, because the offset gap means the ring often sits half on one and half on the other.

The theme problem is where most of the failures hide. I run the check against every background the element can appear on. Light theme, dark theme, and any colored sections like a hero band or a footer with an inverted palette. One outline color almost never passes against all of them.

My fix is to tie the ring color to the theme, not hardcode it:


:root { --focus-ring: #1a1a1a; }
[data-theme="dark"] { --focus-ring: #f5f5f5; }

:focus-visible {
  outline: 2px solid var(--focus-ring);
  outline-offset: 2px;
}

For elements that sit on unpredictable backgrounds, like a button over a photo or a video, I add a second ring with a contrasting color so at least one half is always visible:


:focus-visible {
  outline: 2px solid #fff;
  outline-offset: 2px;
  box-shadow: 0 0 0 4px #000;
}

White ring, black halo. One of them wins no matter what's behind it. I'd only reach for the box-shadow here, where I actually need the double layer, and I'd accept the clipping risk because the fallback matters more.

Check the ratio with any contrast tool. Pick the outline color, pick the background, read the number. If it's under 3:1, bump the outline to a thicker 2px or change the color. Don't make the ring thinner to look subtle. Subtle and invisible are the same thing to the person who needs it.

While you're in there, check that focus works in forced-colors mode too. Windows high contrast mode overrides your colors entirely, and outline survives that override where box-shadow sometimes doesn't. That's the other reason I default to outline.

Tab The Whole Page, Mouse Unplugged

This is the test that catches everything the CSS checks miss. I put the mouse away and Tab through the entire page, start to finish, like I have no other option.

The order should follow the visual layout. Top to bottom, left to right, the way you'd read. If focus jumps from the header to the footer and back up to the middle, your DOM order doesn't match your visual order, and a keyboard user is being bounced around the page with no map.

This breaks constantly after a redesign because CSS lets you move things visually without touching the DOM. You use flexbox order or grid placement to put a sidebar on the left that lives at the bottom of the HTML. Looks right, tabs wrong. Fix the DOM order, not the tab order. Resist tabindex with positive numbers; it's a patch that makes the next person's job harder.

Things I watch for on the walk:

A visible focus ring on every single stop, no silent jumps.
Nothing focusable that's hidden. If a mobile menu is closed, its links shouldn't be in the tab order.
No trap. I can Tab out of every modal, dropdown and date picker. If I open something and Tab cycles forever inside with no escape, that's a trap, and Escape should close it.
A skip link as the first stop, so keyboard users can jump past the nav to the main content instead of tabbing through forty menu items on every page.

The modal trap is the one that bites after a component swap. A good modal traps focus on purpose while open, then returns focus to the button that opened it when it closes. A bad one traps focus forever, or dumps you back at the top of the page where you've lost your place entirely. Open every overlay, Tab around, hit Escape, confirm focus landed somewhere sensible.

I also tab through after resizing to a narrow width, because mobile layouts reorder things and hide others. The desktop tab order can be perfect while the mobile one is a mess.

Do this walk once per major view. It takes minutes and it's the closest thing to actually being a keyboard user for five minutes. If you only run one item on this list, run this one. The naming and structure discipline from The Command Naming Convention Every RAXXO Tool Follows is the same spirit: predictable order so nobody gets lost.

Bottom Line

Run the four checks in order and you'll catch almost every focus regression a redesign introduces. Swap in :focus-visible, give the ring 2px of offset, hold it to 3:1 contrast against every background including dark mode, then tab the whole page with the mouse put away.

If I had to keep just one, it's the tab walk. The CSS can look perfect in the stylesheet and still fail in the actual flow, and the only way to know is to use the page the way a keyboard user does.

Add this to your pre-ship routine and it becomes muscle memory. I keep mine in the same place I keep the rest of my launch gates, because a check you have to remember is a check you'll skip on the busy day.

If you want the full picture of how I set defaults like this once and inherit them across everything I build, the Claude Blueprint walks through the whole approach. Go unplug your mouse and tab your homepage. You'll find at least one dead stop.

Request Validation at the Edge: A Minimal Pattern I Reuse

RAXXO Studios — Mon, 12 Oct 2026 23:44:27 +0000

Reject bad requests at the edge before they touch real logic or a database
A 40-line validator with zero dependencies handles most of my needs
Check shape, types, and size limits first, then business rules later
Returning 400 early cut wasted function runs on one endpoint by half

Most of the junk that hits an API never deserved a full response. A malformed body, a missing field, a 4MB payload where I expected 2KB. I catch all of that at the edge now, before a single line of real logic runs, and the whole backend got calmer for it.

Why the edge is the right place to say no

The edge is the first machine your request touches after DNS. On most platforms that means a worker or function running close to the user, before the request ever reaches your origin server or database. That position is the whole point.

If I validate at the origin, the bad request has already crossed the network, woken up a container, and maybe opened a database connection. I'm paying for compute to tell someone they forgot a field. If I validate at the edge, I reject it in a few milliseconds and the origin never hears about it.

There's a cost angle too.

Edge runtimes bill differently from full origin invocations, and a request that gets rejected in 3ms barely registers. I had one endpoint where roughly half the incoming traffic was malformed scanner noise and duplicate retries. Moving the shape check to the edge meant those never counted as a real function run.

The other reason is blast radius. A validation layer sitting in front of everything is a single place to enforce rules. I don't have to remember to check body.email in six different handlers. I check it once, at the door.

Edge runtimes are also deliberately limited. No full Node API, tight memory, short execution budgets. That sounds like a constraint, but it pushes me toward validation code that's small and fast, which is exactly what validation should be. If my check needs a database lookup or a heavy library, it probably isn't a shape check, it's business logic, and that belongs further in.

I keep the rule simple: the edge decides if a request is well-formed. Whether it's allowed or correct in a business sense comes later. The edge answers "is this even a sensible request" and nothing more.

That one line keeps the validator tiny. It also keeps me from dragging auth tables or inventory checks into a layer that should stay stateless.

The minimal validator I actually reuse

I don't reach for a schema library at the edge unless I have to. Most of my endpoints need maybe five checks, and a dependency-light function covers them. Here's the shape of it.


function validate(body, rules) {
  const errors = [];
  for (const [field, rule] of Object.entries(rules)) {
    const value = body?.[field];
    if (rule.required && (value === undefined || value === null)) {
      errors.push(`${field} is required`);
      continue;
    }
    if (value === undefined) continue;
    if (rule.type && typeof value !== rule.type) {
      errors.push(`${field} must be ${rule.type}`);
    }
    if (rule.max && String(value).length > rule.max) {
      errors.push(`${field} exceeds ${rule.max} chars`);
    }
  }
  return errors;
}

That's it. About 40 lines once I add a couple more checks like enum membership and a regex for email. Calling it looks like this:


const errors = validate(body, {
  email: { required: true, type: "string", max: 254 },
  quantity: { required: true, type: "number" },
  note: { type: "string", max: 500 },
});
if (errors.length) {
  return new Response(JSON.stringify({ errors }), { status: 400 });
}

The order matters. I check required first and continue so a missing field doesn't also throw a type error. A user who forgot email shouldn't get told it's the wrong type too. One clear reason per field.

I return every error at once, not the first one.

Nothing's worse than fixing a field, resubmitting, and getting hit with the next complaint. Collect them, send them back together.

For 90% of endpoints this is enough and it has zero install cost. When an endpoint genuinely needs nested objects or conditional fields, I'll pull in a real schema validator and accept the bundle size. But I reach for the small function first, and most of the time I never outgrow it.

If you want the deeper context on handling repeated and retried requests, Writing Idempotent Webhooks goes through that side.

Check the cheap things before the expensive things

Validation has an order, and getting it wrong wastes the exact compute you were trying to save.

The cheapest check is size. Before I parse anything, I look at Content-Length. If a request claims to be 10MB and my endpoint expects a small JSON body, I reject it with a 413 and never read the stream. Parsing a huge body just to discover it's huge is backwards.

Next is content type. If the header says text/plain and I need JSON, that's a 415, decided in one if. No parse attempt.

Then I parse.

I wrap the parse in a try/catch, because a broken JSON body is a client error, not a server crash. A missing closing brace should return 400, not throw a 500 and page me at night.


let body;
try {
  body = await request.json();
} catch {
  return new Response("Invalid JSON", { status: 400 });
}

Only after the body is a real object do I run the field validator from the last section. Shape checks are cheap but they're the last cheap thing, so they go last among the cheap things.

Everything expensive comes after all of that. Database lookups, auth token verification, rate-limit counters. By the time I'm doing any of that, I already know the request is well-formed. I'm not querying a table to then discover quantity was a string.

I learned to respect ordering the hard way on a different problem. When I measured lookup strategies in Binary Search vs Array.includes(), the lesson was the same: the order and method of a check decides whether it costs microseconds or milliseconds. Validation is no different. Put the 3ms rejections in front of the 300ms ones.

One more thing on size.

Edge runtimes have real memory limits, and a request that tries to stuff a giant string into a field is sometimes less a mistake and more a probe. Cap every string field with a max. It's a free defense against someone trying to blow up your queue or your memory.

What belongs here and what doesn't

The edge validator earns its keep by staying small. The fastest way to ruin it is to let business rules creep in.

Shape, types, and size limits belong at the edge. "Is email a string under 254 characters" is a question I can answer with no outside information. It's pure, stateless, and fast. That's the test I use: if the check needs nothing but the request itself, it can live at the edge.

Does this user actually exist? Is this coupon still valid? Is the item in stock? None of those belong here. They need a database, they need state, and they're slower by nature. Dragging them to the edge forces the edge to talk to your origin anyway, which throws away the latency win you came for.

There's a cleaner way to think about it.

The edge answers "could this request ever be valid." The origin answers "is this request valid right now, for this user, in this state." The first question is about form. The second is about truth. Keep them separate and both layers stay readable.

I also keep error messages at the edge generic on purpose. "Invalid request" plus a list of malformed fields is fine. I don't leak which internal rule failed or whether a user exists, because that validator is public-facing and anyone can poke it. Detailed, state-aware errors come from deeper in, where I've already decided the caller is allowed to know.

Watch out for edge runtime limits while you're at it. Some platforms cap execution time hard, and a validator that accidentally does real work can blow that budget. I once watched a tiny Node process fall over from a different kind of overreach in I Found the Exact Recursion Depth That Crashes Node, and the fix in both cases is the same discipline: know your limits and stay well under them.

The payoff is that the origin code gets simpler. Every handler can assume the body is well-formed, because the only way to reach it is through the door I built. That assumption removes a pile of defensive if checks from the real logic.

Bottom Line

Start with the 40-line validator and only graduate to a schema library when an endpoint genuinely needs nested or conditional rules. Order your checks cheapest-first: size, content type, parse, then shape, then anything that touches state. Keep business rules out of the edge entirely.

If you build one shared validator and run it in front of every endpoint, you get a single place to change rules and a backend that can trust its inputs. That trust is worth more than the code it costs.

I wire this pattern into most of my projects the same way I wire in a few other defaults, and I documented that whole setup in the Claude Blueprint if you want the fuller picture of how I scaffold a new service. Grab the validator, drop it at your edge, and let the junk bounce off the door.

Debounce vs Throttle: I Counted Every Call

RAXXO Studios — Mon, 12 Oct 2026 07:38:55 +0000

Debounce waits for a pause; 25 fast keystrokes collapsed into exactly 1 call at 300 ms
Throttle keeps a steady beat; 60 scroll events at 60 Hz became 11 calls at 100 ms
Debounce alone let a slow, stale search response overwrite the newer one in my test
Pick by the question the UI asks: "when they stop" means debounce, "while it happens" means throttle

Debounce and throttle both cut the number of times a handler runs, and that's where most explanations stop. I wanted numbers, so I wrote both functions, fired fake keystrokes and scroll events at them in Node, and counted every call that came out the other side.

The counts are below. So is the bug that neither of them fixes.

What Each One Actually Does to Your Events

Debounce waits. Every new event resets a timer, and the handler only runs once the events stop for the full wait time. Throttle doesn't wait for a pause. It lets the handler run at most once per window, no matter how many events arrive inside it.

Here are the two versions I tested. Both are small enough to paste into any project without a dependency.


function debounce(fn, wait) {
  let t;
  return function (...args) {
    clearTimeout(t);
    t = setTimeout(() => fn.apply(this, args), wait);
  };
}

function throttle(fn, wait) {
  let last = 0, t = null, pending;
  return function (...args) {
    const now = Date.now();
    const remaining = wait - (now - last);
    pending = args;
    if (remaining <= 0) {
      clearTimeout(t); t = null; last = now;
      fn.apply(this, args);
    } else if (!t) {
      t = setTimeout(() => {
        last = Date.now(); t = null;
        fn.apply(this, pending);
      }, remaining);
    }
  };
}

The throttle has one detail people often leave out: the trailing call. Without it, the last events inside a window get dropped, and a scroll position or slider value can freeze a few pixels short of where the user actually stopped. With it, the final event always lands. In my test the throttled handler received event 59 of 59, the true last one.

The opposite edge matters too. My throttle fires on the first event right away (the leading edge), so a drag handle reacts the instant you grab it. My debounce only fires on the trailing edge, after the quiet period. That's right for search and wrong for a button that should respond to the first click, which is why some libraries offer a leading: true option on debounce as well. If a control feels laggy on the very first touch, check which edge it's firing on before you touch the timing.

If you already use lodash, its _.throttle is built on _.debounce with a maxWait option, so the two are closer relatives than their names suggest. You don't need lodash for either, though.

The Numbers: 25 Keystrokes and 60 Scroll Events

Test one simulated someone typing "debouncing and throttling", which is 25 characters, at one key every 80 ms. That's a fast but realistic typist.

Debounce at 300 ms: 1 call, after the last key.
The same typing with one 450 ms pause halfway through: 2 calls.
Throttle at 300 ms: 8 calls, spread across the whole burst.

Test two simulated one second of scrolling at 60 Hz: 60 events, 16 ms apart.

Throttle at 100 ms: 11 calls.
Debounce at 100 ms: 1 call, after the scrolling stopped.

Those two tests show the whole difference better than any definition. Debounce turned a burst into one final answer. Throttle turned the same burst into a steady beat of intermediate answers.

Why 300 ms for the search box? Fast typists leave something like 80 to 200 ms between keys, so any wait above that collapses a word into one call. 300 sits safely above the typing gap and still feels instant once they stop. The 450 ms test shows the other side of that choice: a real pause mid-word counts as "stopped", which is usually what you want, because the user is probably reading the suggestions.

Neither is better. They answer different questions, and using the wrong one feels broken in a way users notice immediately. A search box on throttle fires requests for "debo", "debounc" and so on, most of them useless. A scroll-linked progress bar on debounce sits frozen for the whole scroll, then jumps once at the end.

Scroll and input are exactly where this shows up in Core Web Vitals. INP, Interaction to Next Paint, has been a Core Web Vital since March 2024, and 200 ms or less counts as good. A heavy handler running on every keystroke is one of the easiest ways to blow past that. I looked at what moved INP on a real store in Six Months of Shopify Web Vitals Data What Actually Moved INP.

The Bug Neither of Them Fixes

This is the part that bites people who did everything "right".

Say the search box is debounced at 300 ms. The user types "deb", pauses for a moment, then finishes "debounce". Two debounced calls fire, 320 ms apart. The short query is the slow one, because it matches more results: 450 ms for "deb", 120 ms for "debounce".

So the responses come back in the wrong order. "debounce" lands first, and then "deb" lands 10 ms later and overwrites it.

In my simulation the UI ended up showing results for "deb" while the input said "debounce". Debounce did its job perfectly. It cut two dozen keystrokes down to two requests. It just has no opinion on the order those requests come back in.

The fix is one AbortController per query:


let controller;

const onSearch = debounce(async (q) => {
  controller?.abort();
  controller = new AbortController();
  try {
    const res = await fetch(`/search?q=${encodeURIComponent(q)}`, { signal: controller.signal });
    render(await res.json());
  } catch (e) {
    if (e.name !== "AbortError") throw e;
  }
}, 300);

Rerun with the abort in place, the same test showed results for "debounce". The older request is cancelled before its response can land, so the order stops mattering. Two things to keep: swallow only AbortError, so real network failures still surface, and create a new controller per call, because an aborted controller stays aborted.

One more leak to close in component code. A debounced call that's still waiting when the component unmounts will fire anyway and try to update something that no longer exists. Give the debounce a cancel and call it in your cleanup:


function debounce(fn, wait) {
  let t;
  const d = function (...args) {
    clearTimeout(t);
    t = setTimeout(() => fn.apply(this, args), wait);
  };
  d.cancel = () => clearTimeout(t);
  return d;
}

In React that's useEffect(() => () => onSearch.cancel(), []), plus aborting the controller in the same cleanup.

Where Each One Belongs

This is the map I'd use. It's organised by the question the interface is asking, because that question decides it faster than any rule about event types.

"Tell me when they stop" is debounce:

Search-as-you-type and autocomplete, at 250 to 300 ms, always with the abort above.
Form validation that calls a server, like "is this username free".
Autosave, with one addition. A pure debounce never saves while someone types without pausing, so add a maxWait (lodash has it) and save at least every few seconds anyway.
Expensive work after a window resize. For layout that reacts to one element's size, ResizeObserver is usually the better tool.

"Keep me updated while it happens" is throttle:

Scroll position for sticky headers, progress bars or analytics.
Drag handles, sliders and anything following the pointer.
Rate-limiting your own API calls from a chatty UI.

For anything that paints, reach for requestAnimationFrame before either. It runs once per frame, which is exactly the rate the screen can show, and it pauses in background tabs for free.

And one case where neither belongs: the double-submitted form. Throttling the click handler looks like a fix and isn't. A slow network or a second tab still gets two orders through. Disable the button on the first click, and make the server treat a repeated request as the same request. That's the server's half of the job, and I covered the storage side of it in Rate Limiting Without Redis: 3 Patterns I Use in Serverless.

Testing all of this doesn't need real waiting. Vitest and Jest both ship fake timers: switch them on, fire your events, advance the clock by the wait time and assert on the call count. That's the same test I ran in Node, minus the real 80 ms sleeps, so it runs in milliseconds and never flakes on a slow CI machine.

Bottom Line

If you remember one test from this, make it the search box. Debounce it at 300 ms, abort the previous request every time, and you've fixed the two problems that make search feel broken: the flood of requests and the stale result.

Everything else falls out of the question the UI is asking. "When they stop" means debounce. "While it happens" means throttle, or requestAnimationFrame if it's drawing something. And if the real problem is a duplicate action, neither timer fixes it, the button and the server do.

The two functions above are dependency-free and tested. Copy them. If you'd rather read more of these build notes by topic, the Lab overview groups every development article in one place.

Which one did you last reach for out of habit when the other one fit better?

The Weekly Operating Rhythm That Keeps a Solo Studio Shipping

RAXXO Studios — Mon, 12 Oct 2026 07:38:19 +0000

Monday is planning only, no building, protects the week's focus
Tuesday through Thursday ship one thing each, nothing parallel
Friday handles publishing, scheduling, and the 30-minute metrics review
I refuse to schedule meetings, standups, and anything open-ended

Running a studio alone means nobody tells you what to do on Tuesday. That sounds like freedom until you realize the absence of a manager is also the absence of structure. The thing that keeps me shipping isn't motivation. It's a small set of rituals I run on the same days every week.

Here's what I actually do, day by day, and the stuff I deliberately keep off the calendar.

Monday Is for Deciding, Not Doing

Monday is planning only. I don't write code, I don't touch a prompt, I don't open the image generator. I sit with a list and decide what the week ships.

The reason is simple. When I let Monday blur into building, I'd start the week reacting to whatever was open in my editor on Friday. That's how you end up three weeks into a feature nobody needs. So Monday is a hard stop on execution.

The planning itself is short. I pick three things, max. One build, one content piece, one operational fix. If a fourth thing feels urgent, it goes on a list for next Monday. Almost always it turns out it wasn't urgent at all.

I also use Monday to look at what's actually in front of users. If a tool has a rough edge, that beats any new feature I had planned. I wrote about the discipline of finishing the unglamorous parts in The Settings Page Every RAXXO Tool Gets Before Launch, and most Monday decisions boil down to that same instinct: polish what exists before chasing what doesn't.

The hardest part of Monday is resisting the dopamine of starting. Building feels productive. Planning feels like procrastination dressed up. But a bad week usually traces back to a Monday where I skipped the decision and just dove in.

I keep the plan written in plain text, one file, three lines. No project management tool. No board with columns. The overhead of maintaining a fancy system would cost me more than the system saves. For a one-person studio, the plan fits on a sticky note, and anything bigger is a tax I refuse to pay.

By Monday afternoon I know exactly what Tuesday, Wednesday, and Thursday look like.

That's the whole point. The decisions are made when I'm fresh and calm, not at 9am Wednesday when I'm staring at a blank editor wondering what matters.

One rule I never break: the Monday plan can shrink but it can't grow. If something breaks, I cut, I don't add.

Tuesday to Thursday: One Thing Per Day

The middle of the week is build time, and the rule is one thing per day. Not one project. One thing.

I used to work on three tools at once, switching when I got stuck. It felt efficient. It wasn't. Every switch cost me 20 minutes of reloading context into my head, and by Friday I'd have three half-finished things and nothing to ship. Now I pick one item from Monday's plan and stay on it until it's done or until the day ends.

Context switching is the silent killer for solo work. There's no teammate holding the other threads in their head. If I drop a task halfway, the entire mental model goes with it, and rebuilding it tomorrow costs real hours.

A typical Tuesday: I'll take one tool, define the smallest useful version, and ship it. I lean hard on Claude for the first pass of anything, which is why I keep a tight setup around it. If you want the full picture of how I structure that work, Claude Blueprint walks through the whole approach.

Wednesday is usually the hard one. It's the day I tackle whatever I was quietly avoiding on Monday. The thing with the ambiguous requirements or the dependency I don't trust. Putting the ugliest task in the middle of the week means I hit it with energy still in the tank, not on a Friday when I'm fading.

I'm deliberately conservative about what I add to a tool. The fewer moving parts, the fewer things break at 2am. I went deep on that philosophy in The One Dependency I Refuse to Add to Any RAXXO Tool, and it shapes most of my Tuesday-to-Thursday decisions.

The output target is modest and that's intentional. One shipped thing a day beats five started things a week. Over a month that's roughly 12 shipped items, which for one person is more than enough to keep a catalog moving.

When I finish early, I don't start the next day's task.

I stop. Pulling tomorrow's work into today just means tomorrow starts empty and I lose the rhythm. The constraint is the feature, not a bug.

Friday Is Publishing and Review

Friday is when the week becomes public. All the content, scheduling, and the one review that actually matters happen here.

I write during the week but I never publish same-day. Everything queues up for Friday. That gap of a day or two catches the typos and the half-baked arguments that look fine when you're close to them and embarrassing by Friday morning.

Social scheduling runs through Buffer, which lets me load a week of posts in one sitting instead of context-switching into social mode every single day. Thirty minutes on Friday replaces what used to be seven small daily interruptions. That's the trade I want: batch the shallow work, protect the deep days.

Then comes the review, and I keep it to 30 minutes with a timer. I look at what shipped, what didn't, and why. The "why" is the valuable part. If something slipped, I want to know if it was a bad estimate or a bad priority, because those get fixed in completely different ways.

I look at a small number of signals: which tools got used, which posts got read, and whatever broke that week. I don't build dashboards and I don't track vanity metrics. A number I won't act on is a number I shouldn't be looking at.

Friday is also when I decide what to kill. A tool that nobody touches after a fair shot gets archived without ceremony. The sunk-cost pull is strong when you built the thing yourself, so having a fixed day to make the call removes the emotion. It's just the Friday review, not a referendum on my judgment.

Keeping up with the tools I depend on happens here too. The pace of change from Anthropic alone means I'd fall behind fast if I didn't check in weekly. When something like Claude Opus 5.5 Ships Cheaper, With Four Breaking Changes lands, Friday is when I read it, decide if it affects my setup, and schedule any migration for a future Tuesday.

By Friday evening the week is closed. Published, reviewed, decided. Nothing dangling into the weekend.

What I Refuse to Schedule

The rhythm works because of what's missing from it as much as what's in it.

I don't schedule meetings. There's no standup, no sync, no recurring call. As one person, a meeting with myself is just thinking with extra steps, and a meeting with anyone else is usually a decision that could've been an email. I protect that empty space on purpose.

I don't schedule open-ended research. "Explore the new thing" is how a full day vanishes with nothing to show. If I want to learn something, it gets a specific question and a time cap. One hour, one question, write down the answer. No wandering.

I don't schedule work on weekends.

This one took me a while to respect. The temptation to grab a few quiet hours on Saturday is constant. But every weekend I worked made the following Monday worse, because the week never actually ended. The rest is part of the system, not a reward for finishing it.

I don't schedule reactive work into the deep days. If a message or a new feature announcement lands on Wednesday, it waits for Friday review or next Monday's plan. The only exception is something actively broken for users, and even then I fix the break and go back to the plan. Nothing else gets to jump the queue.

I also don't schedule perfection passes. A thing ships when it's useful, not when it's flawless. I used to lose entire afternoons polishing details nobody would notice. Now the Monday plan sets the bar and I ship to that bar, no higher.

The staying-current reading has a cap too. The AI space moves fast enough that you could spend every hour just keeping up. Pieces like Anthropic Launches Claude Marketplace With 2,000+ Connectors matter, but they go in the Friday slot, not into Wednesday's build time. Reading about tools isn't the same as shipping with them, and it's easy to confuse the two when you're alone and nobody's measuring your output.

The rhythm isn't about doing more. It's about doing one clear thing per day and letting the rest wait its turn.

Bottom Line

Try the one-thing-per-day rule for a single week before you adopt anything else here. It's the piece that does the most work. Pick one item each morning, finish it, and refuse to start the next until tomorrow. You'll ship more by Friday than you expect, and you'll feel less scattered doing it.

The planning and review rituals matter, but they're scaffolding around that core habit. If Monday-only planning feels too rigid, loosen it. The point isn't my exact schedule. The point is that a solo operator needs structure imposed from somewhere, and if no boss provides it, you build it yourself out of small repeatable rituals.

If you want to see how I keep the actual building fast enough to fit inside this rhythm, Claude Blueprint covers the setup I run every day. Start with one ritual, keep it for a month, and add the next only when the first one sticks.

This article contains affiliate links. If you sign up through them, I may earn a small commission at no extra cost to you. (Ad)