Shipping Less JavaScript Without Rewriting Everything

A colleague asked me last week why our team cares so much about bundle size. I gave a rambling answer, so here is the longer, more organized version.

We had good intentions. We even had a document describing how bundle size should work. The trouble was that the document and the code had quietly gone their separate ways.

Where we started

The first symptom was subtle. Nothing failed outright, but bundle size kept drifting in the wrong direction, and every fix seemed to make the next one harder.

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

How it works

The key insight was to treat bundle size as part of the interface rather than an implementation detail. Once we did that, most of the other decisions followed naturally.

The core of it looks like this:

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

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

Nothing about this is clever, and that's the point. Anyone on the team can read it in a minute and know exactly what it does.

A few things that helped along the way:

Write the migration guide before writing the migration.
Make the default the safe choice, not just the documented one.
Keep the old path around until the new one has survived a real incident.
Agree on what "done" means before the first pull request.

Where this breaks down

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.

We still haven't solved server-side rendering. That's a post for another day, and honestly, I'm not sure we'll get it right the first time either.

Wrapping up

If you take one thing away from this, let it be this: bundle size is a design decision, not a cleanup task. Make it early and make it on purpose.