The Hidden Compatibility Problem in Frontend Deployments

How a simple localStorage change can break both deployments and rollbacks.

The Hidden Compatibility Problem in Frontend Deployments

With a mature continuous delivery pipeline, rolling back a bad release is usually straightforward.

We can simply redeploy a previous build. Even better, with feature flags, we can often disable a problematic feature remotely and fix it at our own pace.

But there is a trap that is easy to overlook, especially in frontend applications.

Rolling back your JavaScript bundle does not roll back the data that already lives in your users’ browsers.

In particular, I’m talking about localStorage.

We often use it to persist user preferences—dark mode, filter settings, selected tabs, recently viewed items, and many other pieces of UI state. It feels harmless because it’s just a small browser API.

But in reality, localStorage behaves much more like a distributed database.

Once a value is written, it lives independently of your deployment pipeline. Your new version may have to read data written by an old version, and after an emergency rollback, your old version may suddenly have to deal with data written by the new one.

Imagine you deploy a feature that changes the format of some persisted data.

The release goes badly, so you immediately roll back.

Your CDN is serving the stable bundle again, your monitoring dashboards look healthy, and the incident appears to be over.

Except it isn’t.

The failed release may already have written a new data format into thousands of browsers. The old code comes back online, tries to read that data, and crashes.

You fixed one production incident, only to create another.

This is a compatibility problem that many frontend teams never think about until they encounter it in production.

In this issue, we’ll take a deep dive into how this happens, look at a few common scenarios, and explore several patterns that make browser storage safe across deployments and rollbacks.

I’ve also made a YouTube video covering the same topic. If you prefer a live walkthrough with code and a working example, feel free to check that out as well.

In this issue, I’d like to go a bit deeper into the underlying design problem and the patterns that can help avoid it.

---

A Simple Feature

To make this more concrete, let’s look at a very common feature.

Imagine a board application with a row of assignee avatars that act as filters.

When users select a few people, we want that preference to survive a page refresh, so we save it in localStorage.

The first implementation is about as simple as it gets.

For board 1, we use the following key:

board-assignee-filter:1

The selected assignees are stored as a comma-separated string:

2,3

And restoring the state is equally simple:

const raw = localStorage.getItem("board-assignee-filter:1");
const assigneeIds = raw ? raw.split(",").map(Number) : [];

Everything works as expected.

The user refreshes the page, and the selected filters come back automatically.

At first glance, this looks like an ordinary frontend feature.

But there is an important detail.

The moment that value is written, it leaves your deployment pipeline and becomes data that lives on a user’s device.

You no longer control it.

---

When the Data Shape Changes

A few weeks later, the product requirements evolve.

Instead of simply selecting assignees, users should be able to choose whether the filter matches any selected user or all of them.

A plain string is no longer enough.

We decide to store a structured object instead:

{
  "assigneeIds": [2, 3],
  "matchMode": "any"
}

The new implementation becomes:

const raw = localStorage.getItem("board-assignee-filter:1");

const filter = raw
  ? JSON.parse(raw)
  : {
      assigneeIds: [],
      matchMode: "any",
    };

If you test this with a clean browser profile, everything works perfectly.

But production users rarely start from a clean state.

Many of them still have the old CSV value:

2,3

The first time they load the new version, the application executes:

JSON.parse("2,3");

And it crashes.

This is the first compatibility problem.

The new code cannot understand data written by the old code.