Skip to main content

Strata Storage Migration Guide

The main package exports the Strata class, but new Strata() starts with no registered adapters. Use defineStorage() for the standard web set, or register adapters explicitly before calling storage methods. Native adapters live in the strata-storage/capacitor entry point.

Web Setup​

import { defineStorage } from 'strata-storage';

const storage = defineStorage({
  defaultStorages: ['indexedDB', 'localStorage', 'memory'],
});

await storage.set('draft', { title: 'First draft' });
const draft = await storage.get<{ title: string }>('draft');

The factory registers the web adapters and initializes lazily on the first operation. Calling initialize() yourself is optional. A manual new Strata() setup must call registerWebAdapters(storage) or storage.registerAdapter(...) before use.

Capacitor Setup​

import { Capacitor } from '@capacitor/core';
import { defineStorage } from 'strata-storage';
import { registerCapacitorAdapters } from 'strata-storage/capacitor';

const storage = defineStorage({
  defaultStorages: Capacitor.isNativePlatform()
    ? ['sqlite', 'preferences', 'memory']
    : ['indexedDB', 'localStorage', 'memory'],
});
await registerCapacitorAdapters(storage);

await storage.set('draft', { title: 'First draft' });

registerCapacitorAdapters() registers Preferences, SQLite, Secure and Filesystem on a native Capacitor platform, then refreshes the instance. It does nothing to native registration in a browser. Import it from the Capacitor subpath, not the package root.

Existing Keys​

The web localStorage and sessionStorage adapters now write with the strata: physical key prefix. The library can adopt its own older unprefixed storage envelopes on read. If an external script reads a physical key directly before Strata loads, configure keyPrefix: false and test that reader before upgrading; configuration explains the ownership check.

Verify the Migration​

  1. Build with the current package exports and inspect every custom new Strata() instance for registration.
  2. Read a known pre-upgrade key, write a new value, reload and read it back.
  3. On iOS and Android, sync the native project and run the device verification guide. Browser tests cannot prove native persistence.