iframe-shared-storage

Tiny hub/client helper that lets you proxy localStorage and indexedDB (via idb-keyval) calls into a cross-origin iframe. The hub runs on a storage-friendly origin, while the client injects a hidden iframe, performs a readiness handshake, and then proxies storage calls through postmsg-rpc.

Highlights

- Drop-in storage facade – use the returned client just like window.localStorage, but every call is executed inside the hub origin.
- Origin isolation – keep your application origin locked down (COEP/COOP, CSP, etc.) while delegating storage access to a lightweight hub page.
- Automatic readiness checks – the client pings the iframe until the hub replies, enforcing a configurable timeout instead of hanging forever.
- Optional diagnostics – enable structured logging per-domain (client, hub, or both) to inspect RPC traffic when debugging.
- Browser + bundler friendly – ship dist/browser.js for

`
Host this file on the origin that is allowed to use the storage APIs you care about.

$3

`ts
import { constructClient } from "iframe-shared-storage";

const storage = constructClient({
iframe: {
src: "https://storage-origin.example.com/hub.html",
messagingOptions: { enableLog: "client" },
iframeReadyTimeoutMs: 1500,
methodCallTimeoutMs: 2000,
methodCallRetries: 2,
},
});

await storage.localStorage.setItem("foo", "bar");
const value = await storage.localStorage.getItem("foo");
await storage.indexedDBKeyval?.set("heavy", JSON.stringify({ ... }));
`

For non-bundled apps, the same API is available via the IframeStorage global that dist/browser.js defines:
`html


`

API

$3


Call this once inside the hub iframe. The hub must have a parent window (i.e. it cannot run as a top-level page). It registers handlers for:
- localStorage.setItem/getItem/removeItem/clear/key
- indexedDBKeyval.set/get/del

$3

- Pass { iframe: { src: string } } to inject a hidden iframe that points to your hub URL. The iframe receives an auto-generated iframe-storage-hub id.
- Pass { iframe: { id: string } } to bind to an already-rendered