Store data from your app
Save per-user data from your app with the ambient window.panoplyStorage API — no backend required
Every deployed app gets an ambient window.panoplyStorage client, so your app can remember what each visitor does without standing up a backend. Write against window.panoplyStorage and it works the same whether the app is backed by a real per-app database or by the visitor's browser.
The API
window.panoplyStorage is available as a global before your own scripts run. Every method returns a Promise, so await them.
get(key)→ the stored value, ornullif the key doesn't exist.list(prefix?)→ an array of{ key, value, updatedAt }. Pass aprefixto return only keys that start with it; omit it to list everything.set(key, value)→{ ok: true }.valueis any JSON-serializable data.delete(key)→{ ok: true }.
await window.panoplyStorage.set('score', 42)
const score = await window.panoplyStorage.get('score') // 42, or null if unset
const games = await window.panoplyStorage.list('game:') // [{ key, value, updatedAt }, …]
await window.panoplyStorage.delete('score')
Keys are strings. Values are anything JSON can represent — objects, arrays, numbers, strings, booleans, null.
When a call is refused
A refused call rejects. It never resolves as if it had worked, so await window.panoplyStorage.set(...) only returns when the data was saved. Always catch it: a save that is refused is not stored, and the data is gone on reload.
The error is an Error with the Worker's message and two fields to branch on:
code— a stable string (below). Branch on this, never on the message.status— the HTTP status, or0when the request got no answer.
code | status | What happened |
|---|---|---|
storage_full | 413 | The visitor already has 10,000 keys, or the ~50 MB total would be passed. Delete something first. |
storage_value_too_large | 413 | This one value is over ~1 MB. Split it or store less. |
storage_not_enabled | 501 | The app has no database bound, or no storage key. |
session_expired | 401 | The session ended and could not be renewed in the background. Ask the visitor to sign in again. |
cross_origin | 403 | The call came from another site, another app on panop.ly included. |
storage_bad_request | 400, 405 | The call was malformed: a missing key or value, or a value that is not JSON. A bug in the app. |
storage_backend_error | 500, 503, 502… | Panoply could not read or write the database. Try again shortly. |
network_error | 0 | No answer at all: the visitor is offline, or the request was blocked. |
get, list, set and delete all reject this way. A successful call resolves exactly as listed above.
async function save(key, value) {
try {
await window.panoplyStorage.set(key, value)
return true
} catch (err) {
if (err.code === 'storage_full') {
showMessage('Your storage is full. Delete something and try again.')
} else if (err.code === 'storage_value_too_large') {
showMessage('That is too big to save.')
} else if (err.code === 'session_expired') {
showMessage('You have been signed out. Sign in again to save.')
} else if (err.code === 'network_error') {
showMessage('You are offline. Nothing was saved.')
} else {
showMessage('Could not save (' + err.code + '). Nothing was saved.')
}
return false
}
}
Only show "saved" after the await returns.
The browser-backed variant has no server, so there is no request and status is always 0. get, list, set and delete all reject when they fail, and only a call that worked resolves. A key that is genuinely absent still answers null from get, and an empty store answers [] from list:
code | When |
|---|---|
storage_full | set: the visitor's localStorage is full. |
storage_not_enabled | The browser blocks storage (cookies and site data blocked, or a sandboxed frame). |
storage_bad_request | set: the value cannot be saved as JSON: a BigInt, a circular object, undefined, a function or a symbol. |
storage_backend_error | The browser threw some other error, or a stored value is not valid JSON (get and list name the key). |
A list rejects as a whole if one of the entries it would return cannot be read; get and delete of the other keys are unaffected, and delete removes the unreadable one. The one exception is a value stored as exactly the text undefined, which an older version of the client wrote when an app saved undefined: it reads as absent, so get answers null and list leaves it out.
The same catch handles both variants. cross_origin, session_expired and network_error only come from server-backed apps.
Two backings, one API
The client comes in two variants, injected at deploy time. Your code doesn't change between them:
- Server-backed — the app has a storage slot, so it has its own database. Data is saved server-side, scoped to the signed-in user, and encrypted at rest. It follows the user across devices and browsers.
- Browser-backed — the app has no slot (a free-plan app that isn't using its one storage slot, or storage that wasn't requested). The same API is backed by the visitor's
localStorage: data stays on that one device and browser,updatedAtis alwaysnull, and there are no network calls.
Which one an app gets is decided by your plan and whether the app holds a storage slot — see the plan matrix on the pricing page. Design for the browser-backed case if the app might not have a slot: it still works, the data is just per-device.
Scope, persistence, and privacy
- Server-backed rows are per user — each signed-in visitor sees only their own data — and encrypted at rest. It is not a shared or public database, and not a secrets vault: don't store API keys or credentials in it.
- Browser-backed data lives only in that visitor's browser. Clearing site data removes it, and it never leaves the device.
Limits
Server-backed storage has fixed per-user quotas (they are not tier-derived):
| Limit | Value |
|---|---|
| Keys per user | 10,000 |
| Bytes per value | ~1 MB |
| Total bytes per user | ~50 MB |
They suit preferences, saved state, and cached results — not bulk data or file hosting. Browser-backed storage is bounded by the browser's own localStorage limit instead.
Under the hood — the wire contract
You normally only need the window.panoplyStorage methods above. For tools generating an app, or for debugging, this is what the server-backed client does: it POSTs JSON same-origin to /__panoply/storage with an action and the operation's fields.
| action | request | response |
|---|---|---|
get | { key } | { value } (value is null if absent) |
list | { prefix? } | { items: [{ key, value, updatedAt }] } |
set | { key, value } | { ok: true } |
delete | { key } | { ok: true } |
Behavior at the edges:
- Every refusal is JSON
{ error, code }, with thecodefrom the table in When a call is refused.window.panoplyStoragerejects with it; a tool calling the route directly reads it from the body. - POST only — any other method returns
405. - Same-origin only — a request from another site returns
403with codecross_origin. That includes another app onpanop.ly. 501when the app has no database bound — browser-backed apps never call the route, so this only appears if server-backed code runs somewhere it shouldn't.- When the session has expired, the client renews it in the background, without leaving the page, and retries the call once. If it can't (the visitor signed out of Panoply, or no longer owns the app), the call rejects with
code: "session_expired"and nothing navigates, so your app decides what to show.panoplyFilesandpanoplyVaultbehave the same way.