Персистентность состояния в localStorage и кросс-вкладочная синхронизация
Пользовательские настройки (выбранная тема оформления, язык интерфейса, состояние боковой панели, черновики фильтров) должны переживать перезагрузку страницы и мгновенно синхронизироваться между всеми открытыми вкладками одного приложения.
В @pravosleva/reactive-engine v3.0.1 этот паттерн реализуется без сторонних плагинов с помощью комбинации signal, effect и нативного браузерного события window.addEventListener('storage', ...):
- Гидратация при старте (SSR-safe): При создании сигнала сервис безопасно читает и валидирует JSON из
localStorage(с проверкойtypeof window !== 'undefined', чтобы код не падал при рендеринге на сервере). - Автосохранение через
effect: Любое изменение сигнала автоматически сериализуется вlocalStorageв рамках стандартной микрозадачи планировщика. - Защита от бесконечного цикла при синхронизации вкладок: Событие
'storage'срабатывает только в соседних вкладках браузера (не в той, которая сделала запись). Кроме того, внутренний флагisSyncingFromStorageгарантирует, что обновление сигнала из соседней вкладки не спровоцирует повторную перезапись вlocalStorage.
Практический пример: Сервис пользовательских настроек (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: 'ru',
sidebarCollapsed: false,
}
export class PreferencesService extends AbstractService {
// Флаг защиты от повторной записи при получении данных из соседней вкладки
private isSyncingFromStorage = false
// Инициализируем сигнал начальным значением из localStorage
public preferences = this.engine.signal<UserPreferences>(
this.readFromStorage(),
'prefs:state'
)
// Автоматически сохраняем изменения в localStorage при любой мутации сигнала
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 {
// Игнорируем QuotaExceededError или блокировку storage в режиме инкогнито
}
}, 'prefs:persistEffect')
// Обработчик изменений из других открытых вкладок браузера
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
}
}
// Подписываемся на событие storage как поле класса
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
}
}
/**
* Безопасно парсит и валидирует JSON из хранилища, подставляя дефолты
* для повреждённых или отсутствующих полей.
*/
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 {
// Игнорируем ограничения доступа к storage
}
}
}
public dispose() {
this.stopPersistEffect()
this.storageListenerCleanup()
}
}Использование в чистом JS или UI-слое
typescript
import { ReactiveEngine } from '@pravosleva/reactive-engine'
import { PreferencesService } from './PreferencesService.js'
const engine = new ReactiveEngine()
const prefs = engine.inject(PreferencesService)
// Реактивно применяем тему оформления при изменении в текущей или соседней вкладке
engine.effect(() => {
const { theme, locale } = prefs.preferences.value
document.documentElement.dataset.theme = theme
document.documentElement.lang = locale
})
// Переключение темы в текущей вкладке:
// 1. Обновит DOM в текущей вкладке
// 2. Запишет JSON в localStorage
// 3. Мгновенно пробудит событие 'storage' во всех соседних вкладках браузера
prefs.setTheme('dark')Рекомендации для продакшена
- Версионируйте ключи хранилища (
:v1,:v2): При изменении структуры интерфейсаUserPreferencesв новых релизах обновляйте суффиксSTORAGE_KEY. Это защитит приложение от конфликтов со старым форматом данных, застрявшим в браузерах пользователей. - Используйте
BroadcastChannelдля синхронизации без записи на диск: Если нужно синхронизировать между вкладками эфемерные события (например, сигнал «пользователь вышел из аккаунта» или «закрыть модальное окно во всех окнах») без засоренияlocalStorage, создайте внутри сервиса экземплярnew BroadcastChannel('app:auth_sync')и закрывайте его черезchannel.close()вdispose(). - Будьте осторожны с
engine.reactive()при персистентности: Для простых объектов настроек, которые целиком сериализуются черезJSON.stringify, удобнее использовать обычныйengine.signal<UserPreferences>()с иммутабельным обновлением{ ...this.preferences.value, theme }— так эффект сохранения срабатывает ровно один раз за изменение.