Browser Storage Limits, IndexedDB, and Data Durability
Why localStorage breaks note libraries, how IndexedDB scales structured text, and how Fold pairs persistent storage with Markdown ZIP and JSON backups.
Building a genuinely local-first web application forces an honest engineering constraint into the open: client-side storage is fast, yet never infallible.
When a user trusts an app with months of notes, journal entries, and checklists without a remote database behind it, storage durability becomes the primary engineering concern. That starts with knowing why localStorage fails at scale, how IndexedDB allocates disk space, when browsers evict site data, and why portable exports remain essential.
Why localStorage fails real note libraries
Nearly every quick browser prototype begins with window.localStorage because getItem and setItem work synchronously in two lines of code. While that simplicity fits lightweight preferences like a "paper" or "ink" theme token, it breaks down rapidly as soon as a personal note library grows beyond a handful of entries.
Three structural limits make localStorage unsuitable as a primary document database:
- Synchronous main-thread blocking halts the JavaScript event loop on every read or write, so parsing or stringifying a 2 MB JSON blob during typing causes visible input lag and dropped frames.
- A ~5 MiB origin ceiling fills up twice as fast as expected because JavaScript strings use UTF-16 encoding (two bytes per character), triggering
QuotaExceededErrorafter a few hundred technical notes. - Flat string serialization forces the app to re-stringify every note in your library just to toggle one boolean flag such as
pinned: trueon a single entry.
Inside Fold's IndexedDB engine
IndexedDB removes those bottlenecks by operating as an asynchronous, transactional object store backed by B-tree indexes inside the browser's native storage layer (usually SQLite or LevelDB). Fold initializes database fold_db at schema version 2 with a notes store keyed by id plus secondary indexes on updated and folder.
const request = window.indexedDB.open("fold_db", 2);
request.onupgradeneeded = (event) => {
const db = (event.target as IDBOpenDBRequest).result;
if (!db.objectStoreNames.contains("notes")) {
const store = db.createObjectStore("notes", { keyPath: "id" });
store.createIndex("updated", "updated", { unique: false });
store.createIndex("folder", "folder", { unique: false });
}
};Structured rich text without blocking frames
Unlike localStorage, IndexedDB uses the Structured Clone Algorithm off the main UI thread. Multi-megabyte rich-text documents, task checklists, folder metadata, and timestamps commit asynchronously inside ACID transactions:
| Storage Mechanism | Execution Model | Typical Origin Quota | Indexable Records | Role in Fold |
|---|---|---|---|---|
localStorage | Synchronous (blocks UI) | ~5 MiB (UTF-16) | No | Theme, sound mute state, emergency mirror (fold.notes.v1) |
IndexedDB | Asynchronous transactions | 10% to 60% of free disk | Yes (keyPath and indexes) | Primary canonical note engine (fold_db v2) |
Cache Storage | Asynchronous Request / Response | Shared origin quota | By URL | Offline PWA shell (fold-v2.1), fonts, and static routes |
Fold maintains an emergency fallback mirror in
localStoragefor small vaults and migrates legacylocalStoragenotes intoIndexedDBon first boot so older vaults upgrade cleanly.
Storage eviction mechanics and navigator.storage.persist()
Even when IndexedDB offers hundreds of megabytes of headroom, browsers split origin storage into best-effort and persistent buckets. Under default best-effort rules, browsers may reclaim an origin's IndexedDB data silently during low disk space or after prolonged inactivity unless persistence is granted.
Two engine behaviors drive almost all unexpected browser cleanup:
- Disk pressure (LRU eviction) causes Chromium browsers and Firefox to purge least-recently-used origin buckets when a device's free disk space drops below internal safety thresholds.
- Inactivity caps under Safari's Intelligent Tracking Prevention (ITP) expire script-writable storage (including
IndexedDB) for sites that receive no direct interaction for 7 days, unless installed as a web app or granted persistence.
Requesting durable storage protection
To defend against automatic eviction, Fold calls the standard Web Storage API via navigator.storage.persist() and navigator.storage.estimate():
export async function requestAndMeasureStorage(): Promise<{
isPersisted: boolean;
usagePercent: number;
}> {
let isPersisted = false;
let usagePercent = 1;
if (typeof navigator !== "undefined" && navigator.storage) {
if (navigator.storage.persisted) {
isPersisted = await navigator.storage.persisted();
}
if (!isPersisted && navigator.storage.persist) {
isPersisted = await navigator.storage.persist();
}
if (navigator.storage.estimate) {
const { usage = 0, quota = 0 } = await navigator.storage.estimate();
if (quota > 0) {
usagePercent = Math.min(100, Math.max(1, (usage / quota) * 100));
}
}
}
return { isPersisted, usagePercent };
}When navigator.storage.persist() returns true, the browser marks the origin durable and excludes it from routine disk-pressure eviction. Quota is shared dynamically across IndexedDB and the Cache API per origin (scaling with free disk space in Chromium and Firefox, and up to roughly 60% of disk space for browser apps in Safari/WebKit, with QuotaExceededError guarding exhaustion). Because browsers evaluate persist() silently based on site engagement or PWA installation instead of showing a prompt, Fold checks persistence on startup and shows live status inside the Storage and data trust modal.
Eviction defense with dual-format vault exports
Browser persistence reduces automatic cleanup, yet it cannot protect notes if someone clears all site data, switches laptops, or deletes a browser profile. For complete durability, Fold lets you export your entire vault directly from the Storage and data trust dialog in two complementary formats at any time.
1. Markdown ZIP vaults with YAML frontmatter
Using client-side JSZip assembly with zero server requests, Fold converts every active note from rich editor markup back into clean CommonMark Markdown, preserving headings, blockquotes, links, <mark> highlights (==text==), and interactive tasks (- [x] and - [ ]).
Each note lands inside its folder subdirectory with standard YAML frontmatter:
---
title: "Hardware-grade local notes"
date: 2026-05-06
folder: "Ideas"
tag: "notes"
starred: false
pinned: false
---
# Hardware-grade local notes
Fold is built around **concentric double-framing**, specular reflections, and pure local persistence.Because this follows plain-text conventions, your exported .zip vault opens cleanly in Obsidian, Bear, iA Writer, Git repositories, or any plain-text editor. Fold also embeds fold-vault-manifest.json inside the archive so the same .zip file restores back into Fold with full structure.
2. Full JSON vault backups
For lossless snapshots that preserve exact timestamps, pinned and starred flags, trash state, and internal note IDs, Fold generates timestamped fold-notes-backup-YYYY-MM-DD.json files you can store in iCloud Drive, an encrypted drive, or local Time Machine backups.
Local data hygiene checklist
- Verify Persistent storage active inside Fold's Storage and data trust panel
- Install Fold as an offline PWA on macOS, iOS, or desktop Chrome for stronger origin durability
- Export a
.zipMarkdown vault or.jsonsnapshot after major writing sessions - Keep periodic backups outside browser-managed site data
Pairing persistent browser storage with open-standard local exports delivers quick on-device responsiveness alongside permanent personal ownership.
References and further reading
- MDN Web Docs, Storage quotas and eviction criteria, on origin pools, best-effort LRU eviction, and
QuotaExceededError. - MDN Web Docs, StorageManager.persist() and StorageManager.estimate().
- web.dev, Persistent storage, on how browsers evaluate durability requests across desktop and mobile engines.
Dhairya Darji
@dhairya0707Creator of Fold. Designing quiet, local-first software instruments with mathematical framing, zero telemetry, and durable on-device storage.
Notes without the noise.
Try the local-first IndexedDB workspace right in this browser. No sign-up required.
Open workspaceMore from Field Notes
How to Install Fold as an Offline PWA on Any Device
Step-by-step guide to installing Fold from foldnotes.web.app as a standalone offline PWA on desktop and mobile, plus how cache updates and backups work.
Local-First Note Architecture at Sub-Millisecond Speed
How Fold avoids cloud round-trips by pairing in-memory React state, single-record IndexedDB writes, and BroadcastChannel IPC across open browser tabs.