Persisted Preact signals for every storage driver

# 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

Install @kamod-ch/signals with @preact/signals and Preact as peer dependencies when using the package outside the Kamod UI monorepo.

```bash
pnpm add @kamod-ch/signals @preact/signals preact
```

## Starting example

```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

- [Documentation](https://kamod-ch.github.io/kamod-signals/)
- [Source](https://github.com/kamod-ch/signals)
- [npm](https://www.npmjs.com/package/@kamod-ch/signals)