Roadmap

This page describes where persistent-state is heading and where the current release stops. It lists the planned versions in the order they ship, and the known gaps in 0.3.0, each with a workaround where one exists. Planned work has no dates; each version’s milestone on GitHub lists its issues, and the changelog records what each release actually ships.

Planned

1.0.0 follows the roadmap core, which is 0.4.0 to 0.11.0. Each row is its own version and its own GitHub milestone. The version links to the issues of that milestone.

Version	Item	Priority
0.4.0	Server writes: writeState and resetState in /next for Server Actions and Route Handlers; core serializeStateCookie for other servers	High
0.5.0	Static rendering with cookie state: a documented static mode without the provider, with a hydrated flag to hide values until they are read; PersistentStateProvider inside <Suspense> with Cache Components, tested and documented; <PersistentStateScript>, an inline <head> script that sets attributes or CSS variables from cookies before the first paint, with a CSP nonce; and a middleware helper that rewrites to a prerendered variant per cookie value	High
0.6.0	Vue binding (/vue composable) and Nuxt server reads	High
0.7.0	Svelte binding (/svelte) and SvelteKit server reads	Medium
0.8.0	Solid binding (/solid) and SolidStart server reads	Medium
0.9.0	Async storage: a storage driver interface, an IndexedDB driver, and the loading state hooks need for it (also covers React Native storage)	High
0.10.0	URL-state interop: seed a definition from a search parameter and mirror it back, for shareable links	Medium
0.11.0	Devtools: an inspect() API listing every definition, its value, storage and persistence, and a small in-page panel	Low
1.0.0	API freeze: deprecated aliases removed, semver guarantees from here on	High
1.1.0	Interop: a zustand persist storage and a jotai atomWithStorage storage backed by definitions	Low
1.2.0	Server-synced storage: a driver that syncs through an endpoint you provide, across devices, with an offline queue	Medium
1.3.0	A hosted sync backend (under consideration; depends on 1.2.0 being used)	Low

Known gaps in 0.3.0

Each row describes behavior of the current release that you might not expect, with what you can do about it today.

Gap	Workaround	Planned
set() and reset() throw on the server, so a Server Action or Route Handler cannot change cookie state.	Change the value in the browser, for example in an event handler. Read cookie state on the server with readState() or readCookieState().	0.4.0
Rendering cookie state in the first HTML with PersistentStateProvider or readState() makes the route dynamic, because both call cookies().	Leave the provider out where a short switch after hydration is acceptable; the page stays static. Render the provider in the layout that needs it, not the root layout. With Cache Components, render it inside <Suspense>.	0.5.0
The hooks exist for React only: /react and /next.	The core imports nothing from React. A definition from persistentState() has get(), set(), reset() and subscribe(), which any framework can bind to, and readCookieState() reads cookies from any server runtime.	0.6.0 to 0.8.0
Storage is synchronous: a cookie, localStorage or sessionStorage. A schema must validate synchronously; a schema that returns a promise reports async-schema and yields default.	Use the storage of another library for asynchronous storage, such as React Native’s. The comparison lists what each one offers.	0.9.0
A state whose default is a string reads a stored null as the text "null".	Clear the value with reset() instead of set(null), or give the state a default that is not a string. See stored null and nullable strings.	none
Cookie keys that differ only in how a character is encoded can read and remove each other’s cookie.	Avoid % and characters that encodeURIComponent escapes in cookie keys. See name variants that alias.	none