Lesson 0004 · ~12 minutes

Deal-breakers & integration risks

One skill: run a 60-second design-review scan — when OPFS is the wrong tool, and which production edges kill “just put it in OPFS.”

← Lesson 3 Lesson 5 → Checklist Sync access Root / handles Glossary

Win for this lesson

You can reject a bad OPFS proposal quickly (wrong store, user-visible confusion, “durable forever,” main-thread thrash, lock blindness) and green-light a good one with eyes open on quota and re-hydrate.

External sources still optional

You’ve been lesson-first — fine. This page is self-contained for the quiz. Highest-value later skims: Storage for the web (quota / eviction / spectrum) and Persistent storage.

1. Wrong tool (reject before API details)

Requirement	Usually not OPFS	Prefer
Drafts, entities, offline queues	Fake “files” for rows	IndexedDB
App shell / HTTP assets offline	Directory of Response clones	Cache API (+ SW)
Tiny theme / flag strings	Handle ceremony for a bool	Memory / careful Web Storage
User must open/save real disk paths	Private OPFS root	File System Access pickers
Multi-device source of truth	“OPFS will sync itself”	Server + explicit sync policy

Lesson 1 still holds: OPFS wins for file-shaped content private to this origin — not as a general kitchen sink (web.dev).

2. Private ≠ Finder / Explorer

OPFS is origin-private. Users do not browse it in the OS file manager. Confusing it with user-visible File System Access is a product bug, not a “permissions quirk” (web.dev OPFS).

No picker for the OPFS root — navigator.storage.getDirectory() only.
You cannot move() OPFS entries into the user-visible tree; you copy (main-thread picker + write) if the user needs a real file.
“Where is my file on disk?” is not a support path for OPFS data — design in-app browse/export instead.

3. “Durable forever” is not a promise

OPFS counts toward the origin’s quota with IndexedDB, Cache Storage, and friends. By default storage is best-effort: under disk pressure, browsers may evict site data (often least-recently-used origins on Chromium/Firefox) (storage-for-the-web). Clearing site data / private modes wipe OPFS too.

navigator.storage.estimate() — approximate usage vs quota; check usageDetails.fileSystem when present (web.dev OPFS).
Catch write failures — treat QuotaExceededError as a product path (delete old files, ask the user, stop unbounded growth).
navigator.storage.persist() — request persistent storage for critical local data (permission/heuristic dependent; user can still clear site data) (persistent-storage).
Safari: treat long-lived script-writable storage as hostile under inactivity policies (~7-day interaction caps called out for related stores on WebKit — verify before a hard product claim; home-screen PWAs differ) (storage-for-the-web).

Unbounded growth is self-inflicted

Caching every export, every media take, every temp render “forever” is a quota bomb. Cap retention, namespace folders by generation, and delete on purpose — the browser will not be your product LRU.

4. Main-thread thrash & locks

Main-thread abuse

Huge async writes/reads still compete with rendering. For heavy byte pipelines, plan a dedicated worker (lesson 3). Don’t invent “sync on main for speed.”

Exclusive lock

Default sync access handle is exclusive. Multi-tab / multi-worker writers fail until close() — design ownership, not hope.

Debug tax

DevTools OPFS inspection is still uneven; Chrome’s OPFS Explorer extension is a practical workaround (web.dev). Budget time for it.

5. Sync policy is product, not API

OPFS is a local origin store. Offline packages, conflict resolution, and “server always wins” are features you design. Shipping OPFS without answering who is truth when the network returns? is a deal-breaker for multi-device products — same as IndexedDB.

60-second review checklist

Wrong tool? · Private vs user-visible clear? · Survive eviction / clear-data / Safari? · Quota + delete plan? · Main-thread cost / worker path? · Lock ownership multi-tab? · Sync / re-hydrate explicit?

6. Practice — reject or green-light

Equal-length options. Immediate feedback.

Scenario A

Proposal: store offline multi-paragraph drafts as named files under OPFS instead of keyed records.

Scenario B

Design review claim: “Once written to OPFS it can never disappear until we delete it.” Your response?

Scenario C

Product wants “Open project from disk / Save As…” into paths the user sees in Finder or Explorer.

Scenario D

Two tabs each open a default-mode sync access handle on the same OPFS DB file for writes.

Scenario E

Feature: multi-hundred-MB media re-encode into OPFS. First runtime shape to defend in review?

7. What to remember

Wrong tool first: entities → IDB; HTTP shell → Cache; user paths → pickers; OPFS for file-shaped private bytes.
Best-effort by default — estimate, catch quota, optional persist(), re-hydrate plan, Safari hostility.
Private ≠ Finder; heavy work → dedicated worker; locks need ownership; sync is product.

Ask your teacher Fuzzy bits — Safari policy details, persist heuristics, multi-tab ownership patterns — ask in chat.

Primary source (read next)

web.dev — Storage for the web (quota, eviction, spectrum). Pair with Persistent storage when durability is the debate. Still useful deferred skim: the OPFS article’s worker + debug sections.