ADR 0006: Zustand over Redux, a sunk-cost-aware trade-off

Decision: Stay on Zustand after a failed Redux migration attempt. Why: The migration cost — broken persist middleware, re-typed slices, changed store shape — was visibly larger than any benefit Redux would have added.

Context

Early in the project I needed app-wide state for conversion options, theme, file list, and preview view state. I picked Zustand without running a deep comparison against Redux, Jotai, or Context. I wanted momentum, the store needed to exist in an afternoon, not a week.

This ADR is not about initial choice. This ADR is about what happened later, when the state model had grown and I asked myself whether I had picked the right technology.

The migration attempt

Once the store had accumulated real shape, persisted slices, per-file options, derived state, zoom/pan state, SVG cache, I started to wonder if Redux would be a better long-term fit. Stronger conventions, better devtools story, more structured reducers. I decided to try.

The prototype broke in several places at once:

I was fixing three unrelated things at once in the migration PR, and whatever I fixed, something else would surface. I reverted the whole attempt.

Decision

Stay on Zustand. Because the cost of migration, measured in days of broken state, regression risk, and re-learning, was visibly larger than the expected benefit.

Rationale

“I already have a tool, is it worth the rewrite.”

The two decisions have different decision rules:

When I reverted the Redux prototype, I had been learning, by contrast, what Zustand was actually giving me that I hadn’t previously articulated: minimal ceremony, one-file stores with state + actions co-located, excellent TS inference, and a persist middleware that already fit my needs. The migration attempt turned out to be the clearest audit of the incumbent I could have run.

Consequences

Positive

Negative

Writing this ADR honestly mattered because the portfolio-genre temptation is to say “I weighed Zustand, Redux, and Jotai, and chose Zustand for reasons X, Y, Z.” But that is not what happened. What happened is: picked fast, tried to migrate later, found the migration wasn’t worth it, and made staying a considered call.

Follow-up