Lesson 0005 · ~12 minutes · synthesis

Ship the decision, not the buzzword

One skill: given a feature brief, write a complete file-storage choice — store, tree shape, I/O path, and one risk you own.

← Lesson 4 Playbook (print) Checklist Glossary
Mission payoff

This is the durable skill from MISSION.md: defend an OPFS choice (or rejection) in a design review without hand-waving.

Lesson-only path

You can complete this from lessons 1–4 alone. External web.dev/MDN reads remain optional enrichment, not a gate.

1. The playbook (four gates)

Run in order. Earlier gates reject more options than later ones.

Gate A · Job

What must live on the client? Memory if re-fetch is fine. Web Storage only for tiny strings. Cache Storage for HTTP shell/assets. IndexedDB for structured entities. OPFS for file-shaped private bytes. User-visible pickers for real disk paths. Server for multi-device truth. (Lessons 1, 4)

Gate B · Tree

getDirectory root; folder layout you invent; getFileHandle / getDirectoryHandle (+ create); remove / removeEntry; list with async iteration. Private origin tree — not Finder. (Lesson 2)

Gate C · I/O path

Default: createWritable → write → close; read via getFile. High-throughput / Wasm / random bytes: dedicated worker + createSyncAccessHandle (exclusive lock, buffers, flush/close). (Lesson 3)

Gate D · Ship risks

Wrong tool, private vs UVFS, quota/eviction/persist, Safari hostility, multi-tab locks, main-thread thrash, unbounded growth, sync/re-hydrate policy. (Lesson 4)

Sentence you should be able to say

“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 quota / lock / re-hydrate / privacy-vs-UVFS.”

Keep the print playbook open after this course — compressed form of all five lessons.

2. Practice — full briefs

Pick the best default package. Equal-length options.

Brief A · Offline media library

Podcast app: store multi-MB episode audio offline as files; a worker streams bytes without re-downloading. Same-origin SPA.

Brief B · Offline note drafts

Notes app: multi-KB rich drafts offline, filter by project, reopen days later same browser. Sync may lag.

Brief C · Open / Save As…

Design tool must open a project from a path the user picks and save back to that real disk location (Finder/Explorer).

Brief D · In-browser SQL engine

Product embeds SQLite-wasm; needs a durable on-device DB file with high-throughput random access for large local datasets.

Brief E · “Never lose local files”

Stakeholder pitch: “OPFS holds the only copy of user projects forever, across phones, and never needs a server backup.”

3. What to remember

Ask your teacher Paste a real feature brief from your team and we’ll run the four gates on it. Follow-ups are part of the method.

Optional enrichment (not required)

When you want the deferred primaries: Storage for the web, The origin private file system, Persistent storage, MDN FileSystemSyncAccessHandle.