What Actually Moved Our Largest Contentful Paint

Every codebase has one area everyone is a little afraid to touch. On our team, it was everything related to hydration.

Most of the complexity was accidental. Over the years we'd layered three different approaches to hydration on top of each other, and each one made sense at the time.

Some background

The setup was ordinary: Svelte at the edges, Astro doing most of the heavy lifting, and a handful of scripts nobody wanted to own. It worked well until usage roughly doubled over a single quarter.

When we finally measured, the numbers were worse than anyone guessed. Around 38% of the time spent on a typical change went into working around hydration rather than building anything.

How it works

The fix turned out to be smaller than expected. Instead of adding another layer, we removed one and leaned on what Svelte already gives you out of the box.

Here's a trimmed-down version of what we ended up with:

.card-list {
  container-type: inline-size;
}

@container (min-width: 36rem) {
  .card {
    display: grid;
    grid-template-columns: 12rem 1fr;
    gap: 1.5rem;
  }
}

It's tempting to generalize this into a library. Resist that urge until you've needed it in at least three places.

A few things that helped along the way:

• Agree on what "done" means before the first pull request.
• Measure before and after, even if it's just a rough number in a spreadsheet.
• Pair on the first few changes so the knowledge doesn't live in one head.
• Delete dead code aggressively; it's the cheapest refactor there is.

What it cost us

There are cases where this falls apart. If your team is very small or your traffic is very spiky, the extra moving parts may not pay for themselves.

The biggest cost was social, not technical. Changing how people think about hydration takes much longer than changing the code.

Takeaways

I don't think there's a universal answer here, but I hope this gives you a few ideas to try on your own project. If you do, I'd love to hear how it goes.