Reference · print-friendly

OPFS decision playbook

One page for design reviews. Walk top to bottom; stop when a row rejects the current candidate.

← Lesson 5 Integration checklist Root / handles Sync access Glossary

1. Gate A · Job (which store?)

If…	Prefer…
Re-fetch is cheap; no offline need	Memory only (skip durable client store)
Tiny string flags	sessionStorage / localStorage (sparingly)
HTTP assets / app shell / resource responses	Cache Storage (+ usually a service worker)
Durable structured app data (drafts, entities)	IndexedDB
File-shaped private pipelines (media, exports, DB files)	OPFS
User must open/save real OS paths	File System Access pickers (user-visible FS)
Multi-device source of truth	Server + explicit sync — not OPFS alone

2. Gate B · Tree shape (if OPFS)

Root: await navigator.storage.getDirectory() (no picker)
Invent a folder layout (exports/, media/, generation prefixes)
getFileHandle / getDirectoryHandle with optional { create: true }
Delete: handle.remove() or parent.removeEntry(name); list via async iteration
Private to origin — not visible in Finder/Explorer

3. Gate C · I/O path

Default (main or worker async): createWritable → write → close; read with getFile()
High-throughput / Wasm / random access: dedicated worker + createSyncAccessHandle()
Sync methods: getSize, read, write, truncate, flush, close (buffers, not raw strings)
Default exclusive lock — second exclusive open / createWritable fails until close()
Export to user-visible FS: main-thread picker + copy (not move)

4. Gate D · Ship risks

Wrong tool (entities / HTTP shell / UVFS / multi-device truth)
Best-effort quota; catch QuotaExceededError; bound growth
estimate() / optional persist(); clear-data and Safari hostility still apply
Main-thread thrash on huge byte work — plan a worker
Multi-tab lock ownership for sync access handles
Re-hydrate / backup / conflict policy is product, not OPFS
Debug tax (DevTools uneven; OPFS Explorer extension)

5. Sentence template

“We use OPFS | IndexedDB | Cache | pickers | memory | server because job; tree is folder layout + handles; I/O is writable streams | worker sync access; we own one risk (quota / lock / re-hydrate / private-vs-UVFS).”