kamod-signals · Persisted State · Familiar .value API
Persisted Preact Signals for Every Storage Driver
Reactive state with durable storage — localStorage, sessionStorage, IndexedDB, cookies, and memory — while keeping the familiar @preact/signals .value API.
Decide Which Values Should Survive a Reload before choosing a storage driver. Use a stable key, define a useful initial value, and keep the lifetime of the signal aligned with the screen, session or application that owns it. Pair it with the Component Library when building your interface. Continue with the Full Documentation for the complete package reference.
What the Package Brings
Use persistence for values that should outlive their current render. Decide what the preference belongs to, how long it should survive and how a user can return to the default.
Choose the Right Approach
Choose local storage for small, non-sensitive browser preferences.
A saved browser value is neither account synchronization nor authoritative server data.
Choose session storage when the lifetime should follow that browser session.
Document which values survive refreshes and which should disappear on sign-out.
Review the cookie driver and createCookieContext at the request boundary.
Cookie scope, response headers and request isolation belong to the server integration.
Persistence Built in
persistedSignal and usePersistedSignal sync reactive values to the driver you choose.
Give each preference a stable storage key and a useful initial value. Treat future changes to the stored shape as a migration decision, rather than assuming every returning visitor has fresh data.
Framework Friendly
Works beside Preact components and plain modules — share state across controllers without prop drilling.
Share a signal only when its consumers should share the same value. Keep temporary screen state local, and avoid copying persisted values into a second independently writable store.
SSR-Aware Cookies
createCookieContext and serializeCookie helpers keep cookie-backed signals usable on the server.
Keep request-specific cookie handling at the server boundary. Verify that the server and client agree on the initial value, and check what happens when there is no saved preference.
Installation
Add persistence to your signals setup. Install @kamod-ch/signals alongside @preact/signals and Preact, checking that the versions satisfy the package’s peer requirements. In an existing application, use the same signal runtime already used by your components.
Decide where the value will live. The Usage Example starts with a local browser preference. Before choosing a different storage driver, read Account for the Environment and the Driver Reference; browser storage and request-scoped cookies need different setup decisions.
pnpm add @kamod-ch/signals @preact/signals preactCheck Your Environment
Use your existing package manager and keep the peer dependencies aligned with your application. Compare package.json and your lockfile with the documentation for the version you install; add the package once at the workspace boundary that uses it.
Keep the First Change Small. Start with the usage example, run your project’s typecheck and build, then connect it to a real screen. The Package Overview helps you decide how companion libraries fit together.
Usage
Give the preference a name, a default and an owner. Create a persistedSignal with a specific storage key and driver, then read or write its .value. A shared instance lets several consumers observe the same preference; use usePersistedSignal when the instance should follow a component’s lifetime.
Check the saved value, not just the current screen. Start with a harmless preference, change it, reload and restore its default. The Component Preference Example shows this flow with a versioned key. Review Ownership and Lifetime before moving the signal into a shared module, especially when your application renders on the server.
import { persistedSignal } from "@kamod-ch/signals";
export const theme = persistedSignal("theme", "dark", { storage: "local" });
// later
theme.value = "light";Read the Example
Follow the value from its definition to the interface. Each part below explains a decision to keep when adapting the example.
The key identifies browser storage, while the variable identifies the live signal. Decide whether it is a device preference or belongs to a signed-in account before sharing the key across screens or sessions.
const theme = persistedSignal("theme", "dark", { storage: "local" });Consumers should observe the same instance. Copying the value into unrelated local state creates a second owner that can become stale. Keep derived presentation derived, rather than synchronizing two writable values with effects.
theme.value = "light";Reset restores the initial value; clearing a stored entry is a separate operation. Use an explicit user action for preference resets, and verify the behavior after reload rather than only checking the currently rendered label.
theme.reset();Keep a Preference Local to a Component
A custom hook can keep the persistent preference close to the settings control. The versioned key below leaves room for a future storage-shape change. This example is intentionally a harmless preference, not authentication or private user data.
import { usePersistedSignal } from "@kamod-ch/signals";
import { Button } from "@kamod-ch/ui";
export function DensityPreference() {
const compact = usePersistedSignal("ui:compact:v1", false, { storage: "local" });
return (
<div class="flex flex-wrap gap-2">
<Button aria-pressed={compact.value} onClick={() => { compact.value = !compact.value; }}>
Compact spacing
</Button>
<Button variant="ghost" onClick={() => compact.reset()}>Restore default</Button>
</div>
);
}Try the Boundaries. Toggle, reload and restore the default. Then test without a stored value and with browser storage restricted. For SSR, ensure the first client render agrees with the server; browser-only preferences cannot automatically be known by the server.
Integrate with Your Application
Persist Preferences Deliberately. A color scheme or density setting has a different lifetime from a draft or an account-specific value. Name keys clearly, decide when they should be reset and avoid retaining temporary UI state without a reason.
The module-level usage example demonstrates a shared signal. In a server-rendered application, do not share user-specific mutable state across requests. Follow the package’s SSR and cookie guidance when a preference must be available before hydration.
Keep reads and writes through the signal’s .value interface and review how your chosen driver handles unavailable storage. Plan for old stored values when you change a preference’s shape or allowed options.
Choose the Owner and Lifetime
Name keys by purpose and treat a stored shape as a small data contract. Give defaults the same care as saved values. Decide whether clearing a preference means removing storage, resetting the live value, or both. For account-specific settings, define sign-out behavior and avoid silently applying one user's saved value to the next user on the device.
Account for the Environment
Storage availability, hydration and cross-tab updates are separate concerns. Test the chosen driver in the actual environment instead of assuming all storage behaves like synchronous local storage. If a preference changes layout, make the initial server and client output compatible and avoid a second competing copy of the value in component state.
Connect the Pieces. Reducer State — Use explicit events and transitions when a workflow needs more structure than a persisted preference.
Persistence needs a reset policy as well as a save path. Decide which values remain after sign-out, which expire with the session and which should never be stored at all.
When Something Behaves Differently
Start with the smallest failing interaction. Compare a fresh page with the same page after a change or reload, and keep the package version in your reproduction.
- A value changes back after refresh
- Check the storage driver, key and write path. Make sure the code updates
.valueon the intended persisted signal rather than a separate temporary variable. - A returning visitor sees invalid data
- Inspect the saved shape from older releases. Validate or migrate before using it, and provide a reset path when the value cannot be recovered.
- Two controls disagree
- Confirm that they are meant to share a source and review the driver's synchronization behavior. Matching variable names do not guarantee matching signal instances or storage keys.
If the behavior still differs from the documented API, Check Existing Issues before opening a report. Include the expected result, actual result, package version and a small reproduction without private application data.
API Reference
This page is a Kamod UI overview. Full API docs, driver tables, and SSR cookie examples live on the dedicated kamod-signals docs.
Use this page to understand the integration, then consult the Full API Reference on Live Docs for exact signatures and supported options. Compare those details with the version in your lockfile before adapting an example.
Explore Drivers, API, and Examples
Open the kamod-signals docs for getting started, storage showcases, and SSR cookie guides.
- Before Choosing an API: read its input types, return values and default behavior.
- Before Shipping: review lifecycle or server-rendering notes for the features you use.
- When Behavior Differs: reduce the case to a small example and include your package version in the report.
Accessibility Notes
When signals drive UI chrome (theme, sidebar, locale), reflect state in accessible controls and keep preference changes predictable for keyboard and assistive tech users.
Before You Ship
- Try a fresh visit, a saved preference and an explicit reset.
- Test your chosen driver with unavailable storage and unexpected stored values.
- Verify that account or request-specific data cannot leak through shared module state.
Review the result with Real Content and Keyboard Input. Keep visible labels, loading and error feedback, and focus behavior in sync with the state your application exposes.
Take the Guide with You
Keep the Examples, Integration Decisions and Troubleshooting Notes together in your project, or share them with a coding assistant. This reference works with any assistant; no model-specific setup is needed. Check the installed version and your project’s conventions before applying a suggestion.
# Signals — integration reference
Reactive state with durable storage — localStorage, sessionStorage, IndexedDB, cookies, and memory — while keeping the familiar @preact/signals .value API.
Package: @kamod-ch/signals
## Choose an approach
Use persistence for values that should outlive their current render. Decide what the preference belongs to, how long it should survive and how a user can return to the default.
### A preference across visits
Choose local storage for small, non-sensitive browser preferences.
A saved browser value is neither account synchronization nor authoritative server data.
### A shorter-lived browser value
Choose session storage when the lifetime should follow that browser session.
Document which values survive refreshes and which should disappear on sign-out.
### Server-aware persistence
Review the cookie driver and createCookieContext at the request boundary.
Cookie scope, response headers and request isolation belong to the server integration.
## Installation
**Add persistence to your signals setup.** Install `@kamod-ch/signals` alongside `@preact/signals` and Preact, checking that the versions satisfy the package’s peer requirements. In an existing application, use the same signal runtime already used by your components.
**Decide where the value will live.** The [Usage Example](https://ui.kamod.ch/docs/signals-package/installation#usage) starts with a local browser preference. Before choosing a different storage driver, read [Account for the Environment](https://ui.kamod.ch/docs/signals-package/installation#environment-boundaries) and the [Driver Reference](https://ui.kamod.ch/docs/signals-package/installation#api-reference); browser storage and request-scoped cookies need different setup decisions.
```bash
pnpm add @kamod-ch/signals @preact/signals preact
```
## Starting example
**Give the preference a name, a default and an owner.** Create a `persistedSignal` with a specific storage key and driver, then read or write its `.value`. A shared instance lets several consumers observe the same preference; use `usePersistedSignal` when the instance should follow a component’s lifetime.
**Check the saved value, not just the current screen.** Start with a harmless preference, change it, reload and restore its default. The [Component Preference Example](https://ui.kamod.ch/docs/signals-package/installation#put-it-to-work) shows this flow with a versioned key. Review [Ownership and Lifetime](https://ui.kamod.ch/docs/signals-package/installation#state-and-lifetime) before moving the signal into a shared module, especially when your application renders on the server.
```tsx
import { persistedSignal } from "@kamod-ch/signals";
export const theme = persistedSignal("theme", "dark", { storage: "local" });
// later
theme.value = "light";
```
### Give the Saved Value a Clear Owner
The key identifies browser storage, while the variable identifies the live signal. Decide whether it is a device preference or belongs to a signed-in account before sharing the key across screens or sessions.
```tsx
const theme = persistedSignal("theme", "dark", { storage: "local" });
```
### Read and Write through One Signal
Consumers should observe the same instance. Copying the value into unrelated local state creates a second owner that can become stale. Keep derived presentation derived, rather than synchronizing two writable values with effects.
```tsx
theme.value = "light";
```
### Provide an Explicit Reset
Reset restores the initial value; clearing a stored entry is a separate operation. Use an explicit user action for preference resets, and verify the behavior after reload rather than only checking the currently rendered label.
```tsx
theme.reset();
```
## Keep a Preference Local to a Component
A custom hook can keep the persistent preference close to the settings control. The versioned key below leaves room for a future storage-shape change. This example is intentionally a harmless preference, not authentication or private user data.
File: src/components/DensityPreference.tsx
```tsx
import { usePersistedSignal } from "@kamod-ch/signals";
import { Button } from "@kamod-ch/ui";
export function DensityPreference() {
const compact = usePersistedSignal("ui:compact:v1", false, { storage: "local" });
return (
<div class="flex flex-wrap gap-2">
<Button aria-pressed={compact.value} onClick={() => { compact.value = !compact.value; }}>
Compact spacing
</Button>
<Button variant="ghost" onClick={() => compact.reset()}>Restore default</Button>
</div>
);
}
```
Toggle, reload and restore the default. Then test without a stored value and with browser storage restricted. For SSR, ensure the first client render agrees with the server; browser-only preferences cannot automatically be known by the server.
## Ownership and environment
Name keys by purpose and treat a stored shape as a small data contract. Give defaults the same care as saved values. Decide whether clearing a preference means removing storage, resetting the live value, or both. For account-specific settings, define sign-out behavior and avoid silently applying one user's saved value to the next user on the device.
Storage availability, hydration and cross-tab updates are separate concerns. Test the chosen driver in the actual environment instead of assuming all storage behaves like synchronous local storage. If a preference changes layout, make the initial server and client output compatible and avoid a second competing copy of the value in component state.
Persistence needs a reset policy as well as a save path. Decide which values remain after sign-out, which expire with the session and which should never be stored at all.
## Troubleshooting
### A value changes back after refresh
Check the storage driver, key and write path. Make sure the code updates .value on the intended persisted signal rather than a separate temporary variable.
### A returning visitor sees invalid data
Inspect the saved shape from older releases. Validate or migrate before using it, and provide a reset path when the value cannot be recovered.
### Two controls disagree
Confirm that they are meant to share a source and review the driver's synchronization behavior. Matching variable names do not guarantee matching signal instances or storage keys.
## Resources
- [Dedicated documentation](https://kamod-ch.github.io/kamod-signals/) — Exact signatures, supported options and deeper examples.
- [Source & release history](https://github.com/kamod-ch/kamod-signals) — Implementation, release notes and the project’s issue tracker.
- [Published package](https://www.npmjs.com/package/@kamod-ch/signals) — Compare the version and peer requirements with your lockfile.
When copying or distributing source, retain the applicable license and attribution notices from the version you use.
## Companion packages
Persistence gives a value a longer life. Keep the surrounding behavior, domain events and display text with the packages that own those responsibilities.
### Hooks — Keep the temporary bits temporary
[`@kamod-ch/hooks`](https://ui.kamod.ch/docs/hooks-package/installation)
Save the user’s preference, but keep an open menu or unfinished hover interaction local. Hooks help a component manage its own behavior while the persisted signal remains the single source for the durable value.
### State — Separate remembering from deciding
[`@kamod-ch/state`](https://ui.kamod.ch/docs/state-package/installation)
Use a reducer when a feature needs explicit domain transitions. If selected preferences also need persistence, define the read/write boundary deliberately; the State signals bridge does not automatically persist a store through this package.
### i18n — Restore a preference, then resolve a locale
[`@kamod-ch/i18n`](https://ui.kamod.ch/docs/i18n-package/installation)
A saved language identifier can inform the translation setup after validation. Specify precedence between storage, routing and server data, and resolve the initial locale consistently so restoring a preference does not flash the wrong language.
## Make a preference earn its place.
Connect one harmless display setting to a Switch, reload the page and offer a clear reset. Test an older stored value too: a preference is only convenient when returning visitors can recover from changes to its shape.
[Connect a preference control](https://ui.kamod.ch/docs/switch/installation)
Check fresh storage, unavailable storage, sign-out behavior and restoring the default.
[All packages](https://ui.kamod.ch/docs/packages) · [The wider ecosystem](https://ui.kamod.ch/docs/ecosystem)
Sources & Attribution
This integration guide accompanies @kamod-ch/signals, maintained in the Kamod ecosystem. The Dedicated Documentation is the reference for package APIs; examples here show how those APIs fit into a Kamod UI application.
Keep the Source Close
Look it up, then buildWhen copying or distributing source, retain the applicable license and attribution notices from the version you use.
Good Company for Signals
Three useful connectionsPersistence gives a value a longer life. Keep the surrounding behavior, domain events and display text with the packages that own those responsibilities.
Make a Preference Earn Its Place.
Connect one harmless display setting to a Switch, reload the page and offer a clear reset. Test an older stored value too: a preference is only convenient when returning visitors can recover from changes to its shape.
Check fresh storage, unavailable storage, sign-out behavior and restoring the default.
You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.
Connect the Foundation
Return to Choose Your Companion Packages to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.
Build the Surrounding Screen
Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.
Make the Result Hold Up
Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.
Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.