Persisted Zustand data that no longer matches your store's shape

I changed the shape of my store, and now a returning visitor's saved localStorage data throws on load.

IntermediateRead 6 minDoing: about an hour7 steps

▶ Start

What you'll have at the end

A version number and migrate function that upgrades old saved state instead of crashing on it

Before you start

You need

A Zustand store already wrapped in persist and saving to the browser, plus a planned change to one field's shape that would make an existing saved value stop matching your code.

Not covered

Choosing a different storage backend for persist, or reshaping more than one field in the same release. This recipe walks one field through one version bump; the same pattern scales to more.

Leans on

7 steps

Where to go next

Save a user's settings in localStorage so a refresh doesn't lose them

for a plain localStorage settings object with no persist middleware, where discarding an incompatible saved value on sight was enough and no dedicated migrate hook exists

Checked 22 Aug 2026

Part of the Frontend State Management Beyond Redux cookbook