DEV Community

Cover image for Utilizing Local Storage in React Components: A Comprehensive Guide
Radzion Chachura
Radzion Chachura

Posted on • Originally published at radzion.com

Utilizing Local Storage in React Components: A Comprehensive Guide

Watch on YouTube | 🐙 GitHub

Using local storage in React components may not be as straightforward as it seems. After years of React development, I've finally arrived at a bulletproof solution which I'm happy to share.

usePersistentState hook

Let's examine the solution from top to bottom. We'll interact with the local storage through the usePersistentState hook or the managePersistentState function. We can think of the usePersistentState hook as a variant of the useState hook, which maintains the value across remounts and app visits. To use the hook, we need to provide the value type, key, and initial value.

const [prefferedTheme, setPrefferedTheme] = usePersistentState<ThemePreference>(
  PersistentStateKey.ThemePreference,
  "dark"
)
Enter fullscreen mode Exit fullscreen mode

Though the code may seem somewhat lengthy, it can always be encapsulated within a custom hook for convenience:

const useThemePreference = () => {
  return usePersistentState<ThemePreference>(
    PersistentStateKey.ThemePreference,
    "dark"
  )
}

// in component
const [prefferedTheme, setPrefferedTheme] = useThemePreference()
Enter fullscreen mode Exit fullscreen mode

managePersistentState function

There are situations where our component doesn't need to listen for changes of the local storage value, in those cases we simply want to either save or read the value from the local storage at specific moments.

import { useRouter } from "next/router"
import { useCallback } from "react"
import { Path } from "router/Path"
import {
  PersistentStateKey,
  managePersistentState,
} from "state/persistentStorage"

const persistentPath = managePersistentState<string>(
  PersistentStateKey.PathAttemptedWhileUnauthenticated
)

export const useAuthRedirect = () => {
  const { replace, pathname } = useRouter()

  const toAuthenticationPage = useCallback(() => {
    persistentPath.set(pathname)
    replace(Path.SignIn)
  }, [pathname, replace])

  const toAuthenticatedPage = useCallback(() => {
    persistentPath.get()
    const destination = persistentPath.get() ?? Path.Home
    replace(destination)
    persistentPath.set(undefined)
  }, [replace])

  return {
    toAuthenticationPage,
    toAuthenticatedPage,
  } as const
}
Enter fullscreen mode Exit fullscreen mode

For instance, within the useAuthRedirect hook, we may want to save the path accessed by an unauthenticated user. This would enable redirection to that same path after logging in. The managePersistentState function will return an object with get and set methods to read from, and write values to, local storage. We need to provide the value type and the key, but the initial value isn't necessary.

PersistentStateKey enum

In both the usePersistentState hook and the managePersistentState function, we use the PersistentStateKey enum. This enum contains all the keys used to store values in local storage. The idea is to keep all keys in one place to avoid inadvertently using the same key for different values.

export enum PersistentStateKey {
  OnboardedToBreak = "onboarded-to-break",
  AuthToken = "token",
  AuthTokenExpirationTime = "tokenExpirationTime",
  FocusDuration = "focusDuration",
  HasTimerSoundNotification = "hasTimerSoundNotification",
  HasTimerBrowserNotification = "hasTimerBrowserNotification",
  HasBreakBrowserNotification = "breakBrowserNotification",
  HasBreakSoundNotification = "breakSoundNotification",
  HasBreakAutomaticBreak = "hasBreakAutomaticBreak",
  UnsyncedSets = "unsyncedSets",
  LastPromptToKeepWorkingWasAt = "lastPromptToKeepWorkingWasAt",
  HadFocusOnboarding = "hadFocusOnboarding",
  FocusSounds = "focus-sounds-5",
  SidebarInstallPromptWasRejectedAt = "sidebarInstallPromptWasRejectedAt",
  SelectedSleepAdvice = "selectedSleepAdvice",
  ThemePreference = "themePreference",
  YesterdayRetroWasAt = "yesterdayRetroWasAt",
  LastWeekRetroWasAt = "lastWeekRetroWasAt",
  SupportOnboardingWasAt = "supportOnboardingWasAt",
  BreakEducationWasAt = "breakEducationWasAt",
  TwoDayRuleEducation = "twoDayRuleEducationWasAt",
  FocusDurationEducationWasAt = "focusDurationEducationWasAt",
  FocusSoundsView = "focusSoundsView",
  ScheduleEducationWasAt = "scheduleEducationWasAt",
  HabitsEducationWasAt = "habitsEducationWasAt",
  PathAttemptedWhileUnauthenticated = "pathAttemptedWhileUnauthenticated",
  ReactQueryState = "reactQueryState",
}
Enter fullscreen mode Exit fullscreen mode

A union type could be used for the keys, but at some point we might need to change the data format of a value and therefore need a version for the key.

persistentState file

Let's dive deeper into the implementation. Throughout the process, we establish the usePersistentState hook and managePersistentState functions via other functions. This approach, while seemingly elaborate, is perfect for reusability. When I want to include local storage on a new app, all I do is create a persistentState file, which is a few lines of code. All logic code remains hidden in a different package which is greatly beneficial in the case of a monorepo.

import { TemporaryStorage } from "@increaser/ui/state/TemporaryStorage"
import { LocalStorage } from "@increaser/ui/state/LocalStorage"
import { createPersistentStateHook } from "@increaser/ui/state/createPersistentStateHook"
import { createPersistentStateManager } from "@increaser/ui/state/createPersistentStateManager"

export enum PersistentStateKey {
  ThemePreference = "themePreference",
  // ...
}

export const persistentStorage =
  typeof window !== "undefined"
    ? new LocalStorage<PersistentStateKey>()
    : new TemporaryStorage<PersistentStateKey>()

export const usePersistentState =
  createPersistentStateHook<PersistentStateKey>(persistentStorage)

export const managePersistentState =
  createPersistentStateManager<PersistentStateKey>(persistentStorage)
Enter fullscreen mode Exit fullscreen mode

Within the persistentState file, we begin by creating an enum with keys and continue with the initialization of the persistentStorage object. Depending upon whether local storage is avaliable or not, we use TemporaryStorage or LocalStorage. Both of these implement the same PersistentStorage interface. They include a way to get and set items and a method to subscribe to the changes of the value, else we won't be able to track the changes in our usePersistentState hook.

export type OnValueChangeListener<T> = (newValue: T, oldValue: T) => void

export interface PersistentStorage<T extends string> {
  getItem<V>(T: string): V | undefined
  setItem<V>(T: string, value: V): void
  addValueChangeListener<V>(key: T, listener: OnValueChangeListener<V>): void
  removeValueChangeListener<V>(key: T, listener: OnValueChangeListener<V>): void
}
Enter fullscreen mode Exit fullscreen mode

LocalStorage & TemporaryStorage implementation

The getItem method retrieves the value from localStorage and parses it. We first handle null and undefined cases, then attempt to parse the value as JSON. If this fails, the value is returned as a string.

import { OnValueChangeListener, PersistentStorage } from "./PersistentStorage"

export class LocalStorage<T extends string> implements PersistentStorage<T> {
  listeners: Record<string, OnValueChangeListener<any>[]> = {}

  getItem<V>(key: T) {
    const item = localStorage.getItem(key)

    if (item === null) return undefined

    if (item === "null") return null as never as V
    if (item === "undefined") return undefined

    try {
      return JSON.parse(item) as V
    } catch {
      return item as never as V
    }
  }
  setItem<V>(key: T, value: V) {
    const oldValue = this.getItem(key)
    const newValue = JSON.stringify(value)
    if (oldValue === newValue) return

    if (value === undefined) {
      localStorage.removeItem(key)
    } else {
      localStorage.setItem(key, newValue)
    }

    const listeners = this.listeners[key] || []

    listeners.forEach((listener) => {
      listener(value, oldValue)
    })
  }
  addValueChangeListener<V>(
    key: string,
    listener: OnValueChangeListener<V>
  ): void {
    if (!this.listeners[key]) {
      this.listeners[key] = []
    }

    this.listeners[key].push(listener)
  }
  removeValueChangeListener<T>(
    key: string,
    listener: OnValueChangeListener<T>
  ): void {
    this.listeners[key] = (this.listeners[key] || []).filter(
      (l) => l !== listener
    )
  }
}
Enter fullscreen mode Exit fullscreen mode

In the setItem method, we verify whether the value has changed. If it has, we update the value in local storage and alert all listeners subscribed to that value's changes.

The addValueChangeListener and removeValueChangeListener methods simply add and remove listeners from the listeners object.

The TemporaryStorage follows the same logic, but uses a basic object to store values instead of local storage.

import { OnValueChangeListener, PersistentStorage } from "./PersistentStorage"

export class TemporaryStorage<T extends string>
  implements PersistentStorage<T>
{
  storage: Record<string, unknown> = {}
  listeners: Record<string, OnValueChangeListener<any>[]> = {}

  getItem<V>(key: T) {
    return this.storage[key] as V
  }
  setItem<V>(key: T, value: V) {
    const oldValue = this.getItem(key)
    if (oldValue === value) return

    if (value === undefined) {
      delete this.storage[key]
    } else {
      this.storage[key] = value
    }

    const listeners = this.listeners[key] || []

    listeners.forEach((listener) => {
      listener(value, oldValue)
    })
  }
  addValueChangeListener<V>(
    key: string,
    listener: OnValueChangeListener<V>
  ): void {
    if (!this.listeners[key]) {
      this.listeners[key] = []
    }

    this.listeners[key].push(listener)
  }
  removeValueChangeListener<T>(
    key: string,
    listener: OnValueChangeListener<T>
  ): void {
    this.listeners[key] = (this.listeners[key] || []).filter(
      (l) => l !== listener
    )
  }
}
Enter fullscreen mode Exit fullscreen mode

createPersistentStateHook and createPersistentStateManager functions

The createPersistentStateHook function takes the storage object and returns the usePersistentState hook. The hook utilizes the useState hook to duplicate the value from local storage and trigger the component to rerender when the value changes. If there's no value in local storage, we'll use the initial value but will not update local storage with the initial value to avoid superfluous rerenders. We use the useEffect hook to update the state. By subscribing to local storage value changes, we can refresh the state whenever the value changes, and unsubscribe from the changes when the component is dismounted.

import { OnValueChangeListener } from "./PersistentStorage"
import { useCallback, useEffect, useState } from "react"
import { PersistentStorage } from "./PersistentStorage"

export function createPersistentStateHook<T extends string>(
  storage: PersistentStorage<T>
) {
  function usePersistentState<V>(key: T, initialValue: V) {
    const [value, setValue] = useState<V>(() => {
      const valueFromStorage = storage.getItem<V>(key)

      return valueFromStorage === undefined ? initialValue : valueFromStorage
    })

    useEffect(() => {
      const onValueChange: OnValueChangeListener<V> = (newValue) => {
        setValue(newValue)
      }

      storage.addValueChangeListener(key, onValueChange)

      return () => storage.removeValueChangeListener(key, onValueChange)
    }, [key])

    const setPersistentStorageValue = useCallback(
      (newValue: V) => {
        storage.setItem(key, newValue)
      },
      [key]
    )

    return [value, setPersistentStorageValue] as const
  }

  return usePersistentState
}
Enter fullscreen mode Exit fullscreen mode

The createPersistentStateManager function is a small wrapper that returns an object with get and set methods, which read and write values to local storage for a particular key.

import { PersistentStorage } from "./PersistentStorage"

export function createPersistentStateManager<T extends string>(
  storage: PersistentStorage<T>
) {
  function managePersistentState<V>(key: T) {
    return {
      get: () => storage.getItem<V | undefined>(key),
      set: (value: V | undefined) => storage.setItem(key, value),
    }
  }

  return managePersistentState
}
Enter fullscreen mode Exit fullscreen mode

Top comments (0)