@k8ordo/state

Declare state by where it lives. Four places — URL search params, the history entry, localStorage, memory — each typed by one zod schema, from which the server read, link building and the subscription are all derived.

npm GitHub

Running on this very page

The controls below rewrite the real URL: definePageState updates flow through this site’s router (@k8ordo/router, which intercepts the Navigation API). The theme toggle in the header stores through defineLocalState — its current value is the theme row.

tab

page1

URL: no query (all defaults)
theme: following the system

The page steppers push, so the browser back button rewinds them one by one. The tabs replace, refining the current entry. Copy the URL and the state travels with it. Hand-edit ?page=0 into the URL and the schema drops it to the default.

Features

Declared by where it livesURL, history entry, localStorage, memory. Lifetime and sharing scope are decided by the place you declared, not by how the code happens to be written.
One source: the schemaparseUrl, link building and the salvage of stale data all derive from the schema you wrote. A search form can share the very same schema with @k8ordo/form.
Rides the Navigation APIThe URL and the hidden entry state are two faces of one history entry: updated atomically in a single navigate, restored together by the back button.
Subscribe per keyList the keys you read and updates to any other field never re-render you. The schema fixes the key set, so change detection is exact.
Invalid values never renderupdate passes the schema on the spot, and a hand-edited URL param falls back to its own default, field by field. Defaults are omitted from the query, so the same state always makes the same URL.
The server can read itURL state reads typed in an RSC via parseUrl. Links and GET forms work under any router, before JavaScript loads.

Documentation

The guide and reference ship inside the npm package. An AI coding assistant reads the exact installed version out of node_modules/@k8ordo/state/docs/.

Home