A small, framework‑agnostic utility for syncing cookies, localStorage, and sessionStorage with application state.
npm install synced-storageBattle-tested, framework-agnostic utility for syncing cookies, localStorage, and sessionStorage with application state. Ships with first-class React bindings — adapters for Svelte, SolidJS, and Vue are on the way.
- Unified API — read, write, and subscribe to cookies and web storage through the same interface
- SSR-ready — hydrate cookie values on the server; the client picks up seamlessly
- Cross-tab & same-tab sync — storage changes propagate across tabs via native StorageEvent and within the same tab via synthetic events
- Key expiration — set a Date on any storage key and it auto-resets when it expires
- Functional setState — setState(prev => ...) always receives the latest value, no stale closures
- Portable core — zero React dependency; use the core with any framework
- Tiny footprint — single production dependency (universal-cookie)
- Tree-shakeable — ESM + CJS with sideEffects: false
- Fully typed — written in TypeScript with exported declarations
``bash`
npm install synced-storage
Use the storage core directly — no React required.
`ts
import { CookieClient } from "synced-storage/core";
const client = new CookieClient();
const store = client.getOrCreateStore("theme", "light");
store.subscribe(() => {
console.log(theme changed to ${store.getItem()});
});
store.setItem("dark");
`
`tsx
import { cookies } from "next/headers";
import { SyncedStorageProvider } from "synced-storage/react";
export default async function RootLayout({ children }) {
return (
$3
tsx
import { useCookieState } from "synced-storage/react";function PersonDetails() {
const [person, setPerson] = useCookieState("person", {
name: "Jane",
age: 30,
});
return (
{person.name}, {person.age}
);
}
`$3
tsx
import { useStorageState } from "synced-storage/react";type Theme = "light" | "dark";
function ThemeToggle() {
const [theme, setTheme] = useStorageState("theme", "light", {
strategy: "localStorage", // or "sessionStorage"
});
return (
);
}
`Exports
| Entry point | Contents |
|---|---|
|
| CookieClient, StorageClient, CookieStore, StorageStore |
| synced-storage/react | useCookieState, useStorageState, SyncedStorageProvider |Example
example/` folder. It demonstrates SSR cookies, client hydration, and synced web storage.MIT