Breaking schema changes
A persisted field is renamed or removed and old storage must be distinguished from the new schema.
Zustand · Pipe
version
The persist middleware's version option labels the persisted state format. Change it for breaking storage changes, and use migration logic to convert older data to the current shape.
- Since
- >=3.6.3
How it works
The persist middleware associates stored data with a numeric version. When the configured version differs from the version saved in storage, Zustand does not use that stored value unless migration logic converts it to the current shape.
Syntax
persist(stateCreator, { name, version, migrate })Parameters
| Name | Type | Description |
|---|---|---|
version | number | Numeric identifier for the persisted storage schema; defaults to 0. |
migrate | (persistedState, version) => state | Function receiving persisted state and its version, returning state compliant with the latest version. |
Key points
- Set a higher version when the persisted storage format changes incompatibly, such as after renaming a stored field.
- Migration logic can inspect both the old persisted data and its recorded version.
- The migration result must conform to the current store's persisted shape.
- This option belongs to Zustand's Persist API, which supports programmatic interaction with persisted store data.
Common mistakes
- Changing the version without supplying compatible migration behavior causes the existing persisted value to be ignored.
Example: Versioned persisted state
const useStore = create(persist((set) => ({ count: 0 }), { name: 'counter', version: 1 }))Assign a new version when the persisted state shape changes.
When to use it
Version-aware migrations
Several historical storage formats need conversion into one current state shape.
Storage compatibility checks
An application needs explicit control over whether saved state matches the code's format.
Interview questions
QWhat problem does the persist version option solve?
The version option is a number used to identify the persisted state format. Its default is 0, and changing it lets the application signal a breaking storage change.
Follow-up: How should an application transform old data? Pass a migrate function, which receives the persisted state and its saved version and returns state matching the current version.
QWhen should the version number be changed?
Increase the version when a persisted field is renamed or another breaking storage change occurs. Zustand compares the stored version with the configured code version before accepting the stored value.
Follow-up: What happens when they differ and no migration is provided? The stored value is not used.
QHow does migration use the persisted version?
The migrate callback receives two arguments: the persisted state and its version number. It must return data compliant with the latest version configured in the store.
Follow-up: Why is the version argument useful? It allows one migration function to select the appropriate transformation for different historical formats.
Related
persistmigratePersist APIstorage