Safari Data Storage: IndexedDB, LocalStorage, and OPFS

This article provides a comprehensive overview of how the Safari web browser stores and manages structured client-side data using LocalStorage, IndexedDB, and the Origin Private File System (OPFS). It breaks down the underlying WebKit architecture for each storage mechanism, how they process structured data, their performance implications, and Safari-specific constraints like Intelligent Tracking Prevention (ITP) and storage quotas.

LocalStorage

LocalStorage is the simplest client-side storage mechanism, designed for small amounts of data. However, it does not natively understand structured data.

  • Data Formatting: LocalStorage only supports string key-value pairs. To store structured data (like JavaScript objects or arrays) in Safari, developers must manually serialize the data into a string—typically using JSON.stringify()—before saving it, and deserialize it with JSON.parse() upon retrieval.
  • WebKit Implementation: Under the hood, Safari’s WebKit engine backs LocalStorage with an SQLite database on the user's device. Each origin gets its own SQLite file. When a webpage loads, Safari reads the SQLite database into memory so that read and write operations can happen immediately. Changes are then asynchronously flushed back to the disk.
  • Performance and Limits: Because LocalStorage is a synchronous API, serializing large structured objects blocks the main browser thread, which can freeze the user interface. Safari strictly caps LocalStorage at 5MB per origin.

IndexedDB

IndexedDB is a low-level, NoSQL transactional database built directly into the browser, specifically designed to handle significant amounts of structured data.

  • Data Formatting: Unlike LocalStorage, IndexedDB does not require manual JSON serialization. Safari uses the HTML5 Structured Clone Algorithm to store data. This allows developers to natively store complex JavaScript objects, Arrays, Dates, Maps, Sets, and binary Blob or File objects.
  • WebKit Implementation: Similar to LocalStorage, Safari implements IndexedDB on top of SQLite. However, the architecture is much more complex. WebKit serializes the cloned JavaScript objects into a specialized binary format and stores them as binary large objects (BLOBs) inside SQLite tables. If an object exceeds a certain size, or if it is an actual Blob/File, Safari will store the data as an external file on the disk and simply keep a reference pointer to it in the SQLite database to maintain high performance.
  • Performance and Limits: IndexedDB is entirely asynchronous, preventing main-thread blocking. It also supports indexing, allowing Safari to quickly query specific properties deep within your structured data without scanning every record.

Origin Private File System (OPFS)

The Origin Private File System (OPFS) is a modern storage endpoint provided by the File System Access API. It gives websites access to a private, virtual file system that is hidden from the user's actual file system.

  • Data Formatting: OPFS operates at the byte level, meaning it does not enforce any specific data structure. To store structured data in OPFS, developers write raw binary data (ArrayBuffer or TypedArray) directly to virtual files. In practice, developers often use OPFS in Safari by compiling C-based databases (like SQLite or DuckDB) to WebAssembly (Wasm) and using OPFS as the persistent disk backend for those databases.
  • WebKit Implementation: Safari maps the virtual files and directories created in OPFS directly to obfuscated files on the host operating system's disk (macOS or iOS). Safari supports the FileSystemSyncAccessHandle interface inside Web Workers. This allows the browser to bypass the overhead of the Structured Clone Algorithm and WebKit's internal SQLite wrapper, offering near-native file I/O speeds.
  • Performance and Limits: OPFS is the fastest way to store structured data in Safari. By running a Wasm-based database in a Web Worker using synchronous file handles, applications can read and write structured data directly to the disk without main-thread blocking or serialization bottlenecks.

Safari-Specific Storage Rules

Regardless of whether you choose LocalStorage, IndexedDB, or OPFS, Safari enforces strict privacy and disk-management rules through WebKit:

  • Storage Partitioning: Safari partitions all client-side storage by the top-level site. If an iframe from example.com is embedded on news.com, the structured data saved by the iframe is completely isolated from the data example.com has stored when visited directly.
  • Intelligent Tracking Prevention (ITP): Safari applies a 7-day cap on all script-writable storage (which includes LocalStorage, IndexedDB, and OPFS). If a user does not interact with a website for 7 days, Safari will automatically delete all data stored by these APIs. This restriction is lifted for Web Apps added to the iOS or macOS Home Screen.
  • Unified Quotas: While LocalStorage is locked at 5MB, IndexedDB and OPFS share a dynamic, unified origin quota in Safari. This quota is calculated based on the total available free disk space on the user's device, typically allowing for gigabytes of structured data storage before the browser prompts the user or evicts data.