State Persistence in localStorage & Cross-Tab Synchronization
User preferences (selected UI theme, interface language, sidebar collapse state, filter drafts) should survive page reloads and synchronize instantaneously across all open browser tabs of the same application.
In @pravosleva/reactive-engine v3.0.1, this pattern is implemented without external plugins by combining signal, effect, and the native browser window.addEventListener('storage', ...) event:
- SSR-safe hydration on startup: When creating the signal, the service safely reads and validates JSON from
localStorage(guarding withtypeof window !== 'undefined'so server-side rendering never throws). - Automatic persistence via
effect: Any change to the signal is automatically serialized tolocalStorageinside a standard scheduler microtask. - Infinite-loop protection across tabs: The
'storage'event fires strictly in sibling browser tabs (never in the tab that initiated the write). Additionally, an internalisSyncingFromStorageflag guarantees that updating the signal from another tab never triggers a redundant write back tolocalStorage.
Practical Example: User Preferences Service (PreferencesService.ts)
typescript
import { AbstractService } from '@pravosleva/reactive-engine'
export type ThemeMode = 'light' | 'dark' | 'system'
export type LocaleCode = 'ru' | 'en'
export interface UserPreferences {
theme: ThemeMode
locale: LocaleCode
sidebarCollapsed: boolean
}
const STORAGE_KEY = 'app:user_preferences:v1'
const DEFAULT_PREFERENCES: UserPreferences = {
theme: 'system',
locale: 'en',
sidebarCollapsed: false,
}
export class PreferencesService extends AbstractService {
// Guard flag to prevent redundant writes when applying updates from a sibling tab
private isSyncingFromStorage = false
// Hydrate initial signal state from localStorage
public preferences = this.engine.signal<UserPreferences>(
this.readFromStorage(),
'prefs:state'
)
// Automatically persist changes to localStorage whenever the signal updates
private stopPersistEffect = this.engine.effect(() => {
const current = this.preferences.value
if (this.isSyncingFromStorage || typeof window === 'undefined') return
try {
window.localStorage.setItem(STORAGE_KEY, JSON.stringify(current))
} catch {
// Ignore QuotaExceededError or restricted storage in private browsing modes
}
}, 'prefs:persistEffect')
// Handle storage mutations originating from other open browser tabs
private handleStorageEvent = (event: StorageEvent) => {
if (event.key !== STORAGE_KEY) return
this.isSyncingFromStorage = true
try {
this.preferences.value = event.newValue
? this.parsePreferences(event.newValue)
: DEFAULT_PREFERENCES
} finally {
this.isSyncingFromStorage = false
}
}
// Attach the storage listener as a class field
private storageListenerCleanup = this.attachStorageListener()
private attachStorageListener(): () => void {
if (typeof window === 'undefined') return () => {}
window.addEventListener('storage', this.handleStorageEvent)
return () => {
window.removeEventListener('storage', this.handleStorageEvent)
}
}
private readFromStorage(): UserPreferences {
if (typeof window === 'undefined') {
return DEFAULT_PREFERENCES
}
try {
const raw = window.localStorage.getItem(STORAGE_KEY)
return raw ? this.parsePreferences(raw) : DEFAULT_PREFERENCES
} catch {
return DEFAULT_PREFERENCES
}
}
/**
* Safely parses and validates JSON from storage, falling back to defaults
* for corrupted or missing fields.
*/
private parsePreferences(raw: string): UserPreferences {
try {
const parsed: unknown = JSON.parse(raw)
if (typeof parsed !== 'object' || parsed === null) {
return DEFAULT_PREFERENCES
}
const candidate = parsed as Record<string, unknown>
const theme: ThemeMode =
candidate.theme === 'light' ||
candidate.theme === 'dark' ||
candidate.theme === 'system'
? candidate.theme
: DEFAULT_PREFERENCES.theme
const locale: LocaleCode =
candidate.locale === 'ru' || candidate.locale === 'en'
? candidate.locale
: DEFAULT_PREFERENCES.locale
const sidebarCollapsed =
typeof candidate.sidebarCollapsed === 'boolean'
? candidate.sidebarCollapsed
: DEFAULT_PREFERENCES.sidebarCollapsed
return { theme, locale, sidebarCollapsed }
} catch {
return DEFAULT_PREFERENCES
}
}
public setTheme(theme: ThemeMode) {
this.preferences.value = { ...this.preferences.value, theme }
}
public setLocale(locale: LocaleCode) {
this.preferences.value = { ...this.preferences.value, locale }
}
public toggleSidebar() {
const prev = this.preferences.value
this.preferences.value = { ...prev, sidebarCollapsed: !prev.sidebarCollapsed }
}
public resetToDefaults() {
this.preferences.value = DEFAULT_PREFERENCES
if (typeof window !== 'undefined') {
try {
window.localStorage.removeItem(STORAGE_KEY)
} catch {
// Ignore storage access restrictions
}
}
}
public dispose() {
this.stopPersistEffect()
this.storageListenerCleanup()
}
}Usage in Vanilla JS or UI Layer
typescript
import { ReactiveEngine } from '@pravosleva/reactive-engine'
import { PreferencesService } from './PreferencesService.js'
const engine = new ReactiveEngine()
const prefs = engine.inject(PreferencesService)
// Reactively apply UI theme whenever updated in the current or a sibling tab
engine.effect(() => {
const { theme, locale } = prefs.preferences.value
document.documentElement.dataset.theme = theme
document.documentElement.lang = locale
})
// Switching the theme in the active tab:
// 1. Updates the DOM in the current tab
// 2. Writes serialized JSON to localStorage
// 3. Immediately fires the 'storage' event in all sibling browser tabs
prefs.setTheme('dark')Production Best Practices
- Version your storage keys (
:v1,:v2): Whenever the shape ofUserPreferenceschanges across releases, bump theSTORAGE_KEYsuffix. This prevents runtime conflicts with legacy payloads cached in user browsers. - Use
BroadcastChannelfor disk-free cross-tab events: When you need to broadcast ephemeral events across tabs (such as "user logged out" or "close modal everywhere") without pollutinglocalStorage, instantiatenew BroadcastChannel('app:auth_sync')inside the service and close it viachannel.close()indispose(). - Prefer
engine.signal()overengine.reactive()for persisted settings: For flat preference objects that are serialized as a whole viaJSON.stringify, using a standardengine.signal<UserPreferences>()with immutable updates ({ ...this.preferences.value, theme }) ensures the persistence effect fires cleanly once per update.