origin-snapshot

Export and restore everything portable about a browser origin — localStorage, sessionStorage, IndexedDB, and OPFS — as a single, compact file.

The output is a gzip-compressed binary container (.galaxy), not JSON. Binary payloads (IndexedDB blobs, OPFS game/emulator saves) are stored as raw bytes and the whole thing is gzipped, so there's no base64 inflation and gzip de-duplicates across files. That makes it the smallest practical representation you can build in the browser with zero dependencies. (Brotli would be a touch smaller, but CompressionStream only ships gzip/deflate.)

What's included

| Included | Skipped (and why) | | --------------------------------------- | --------------------------------------------------------- | | localStorage | Cache API — huge, regenerable proxied assets | | sessionStorage (opt-in) | Service-worker registrations — re-register automatically | | IndexedDB (schema + records) | Real/HttpOnly cookies — invisible to JS | | OPFS (full file tree) | Push subscriptions / background sync — device-bound | | Proxied cookies (ride along in storage) | Permissions / WebAuthn / passkeys — origin + device bound |

Install

npm install origin-snapshot

Browser-only (it needs localStorage, indexedDB, OPFS, and CompressionStream). Ships as ESM source — no build step.

Usage

import {
  downloadSnapshot,
  exportOrigin,
  importOrigin,
  readManifest,
} from "origin-snapshot";

// One-liner: build the snapshot and trigger a download.
await downloadSnapshot(); // example.com-2026-06-28.galaxy

// Or get the Blob yourself (upload it, store it, etc.).
const blob = await exportOrigin({ sessionStorage: true });

// Later — on the same origin — restore it.
const file = await pickFile(); // <input type="file">
await importOrigin(file); // wipes + restores each section by default

// Peek at metadata without restoring.
const manifest = await readManifest(file);
console.log(manifest.origin, manifest.createdAt);

API

exportOrigin(options?) => Promise<Blob>

| option | default | description | | ---------------- | ------- | --------------------------------------------------------------------- | | localStorage | true | include localStorage | | sessionStorage | false | include sessionStorage (clears on tab close) | | indexedDB | true | include all IndexedDB databases | | opfs | true | include the OPFS file tree | | databases | — | explicit IndexedDB names for browsers without indexedDB.databases() |

importOrigin(source, options?) => Promise<manifest>

source may be a Blob/File, ArrayBuffer, or Uint8Array.

| option | default | description | | ------- | ------- | ---------------------------------------------------- | | clear | true | wipe each section before restoring (false = merge) |

downloadSnapshot(options?) => Promise<Blob>

exportOrigin plus a browser download. Accepts every exportOrigin option, plus filename.

readManifest(source) => Promise<manifest>

Returns the snapshot metadata (format, version, createdAt, origin, sections) without touching local storage.

Notes & limits

• Same-origin restore. IndexedDB and OPFS are origin-scoped; restore on the origin the snapshot came from.
• Close other tabs before restoring. Recreating an IndexedDB database needs an exclusive connection; another open tab can block it.
• Round-trips structured-clone types — Date, Blob, File, ArrayBuffer, typed arrays, Map, Set, RegExp, bigint, undefined, NaN/Infinity. Circular references are rejected with a clear error.

License

MIT