synced-storage

v1.1.1

Published

10 days ago

A small, framework‑agnostic utility for syncing cookies, localStorage, and sessionStorage with application state.

Downloads

2,414

0High
0Medium
0Low

jeheecheon

cookies localStorage sessionStorage sync react next.js

Synced Storage

A small, framework‑agnostic utility for syncing cookies, localStorage, and sessionStorage with application state.
The core is fully portable — it isn’t tied to React — so adapters for Svelte, SolidJS, and Vue will be added soon.

What this package does

✔ One simple, unified API

Use the same pattern to read, write, and sync values across cookies and browser storage.

✔ Works in both server and client environments

Cookie values can be hydrated on the server, and the browser side seamlessly continues from that state.

✔ Portable core

The core logic does not depend on React, making it easy to support any UI framework.

Installation

npm install synced-storage

Quick start (React)

1. Wrap your app with SyncedStorageProvider

import { cookies } from "next/headers";
import { SyncedStorageProvider } from "synced-storage/react";

export default async function RootLayout({ children }) {
  return (
    <html>
      <body>
        {/* `ssrCookies` is optional – only pass this in SSR env. */}
        <SyncedStorageProvider ssrCookies={(await cookies()).getAll()}>
          {children}
        </SyncedStorageProvider>
      </body>
    </html>
  );
}

2. Cookie state

import { useCookieState } from "synced-storage/react";

export function PersonDetails() {
  const [person, setPerson] = useCookieState("key-for-data", {
    name: "Jehee Cheon",
    age: 99,
  });

  return (
    <div>
      <p>
        {person.name}, {person.age}
      </p>
      <button
        onClick={() => setPerson((prev) => ({ ...prev, age: prev.age + 1 }))}
      >
        Increase age
      </button>
    </div>
  );
}

3. Local/session storage

import { useStorageState } from "synced-storage/react";

type Theme = "light" | "dark";

export function ThemeToggle() {
  const [theme, setTheme] = useStorageState<Theme>("key-for-theme", "light", {
    strategy: "localStorage", // "localStorage" | "sessionStorage"
  });

  return (
    <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
      Toggle theme
    </button>
  );
}

Core usage (any framework)

You can use the storage core directly — no React required.

import { CookieClient } from "synced-storage/core";

const cookieClient = new CookieClient();
const store = cookieClient.getOrCreateStore("theme", "light");

store.subscribe(() => {
  const value = store.getItem();
  console.log(`Changed to ${value}`);
});

store.setItem("dark");

Example

A working Next.js example lives in the example/ folder.
It demonstrates SSR cookies, client hydration, and synced web storage.

License

MIT