Persistence questions test whether you understand the server/client boundary. The URL is visible to both and to the user; cookies are visible to both but small; browser storage is visible only to the client and only after hydration. Choosing wrong produces either hydration mismatches or a server that cannot render what the user expects. This app's own notes and progress features are a worked example of the client-only case.

Know

• URL state for anything the user should share, bookmark or step back through: filters, sorting, pagination, selected tab or item. Read route.query and route.params, write with router.replace (no history entry) or router.push (history), parse and default with a schema because query values are strings, and keep the URL canonical (drop defaults). VueUse's useRouteQuery/useRouteParams (@vueuse/router) give two-way refs.
• Cookies for preferences the server render must know: locale, colour mode, consent, density, and the session. useCookie works on both sides and serialises JSON; set sameSite, secure, sensible maxAge, and keep them small (4 KB each, sent on every request). Server-set cookies need refreshCookie (or the cookieStore flag) to update the client ref.
• localStorage / sessionStorage: synchronous, string-only, ~5 MB, blocks the main thread, not available during SSR, readable by any script on the origin (never tokens). Read it after hydration (onMounted, app:suspense:resolve, or VueUse useStorage with initOnMounted: true) so the first client render matches the server's; render a neutral state until then.
• IndexedDB: asynchronous, structured data, large quotas; use a wrapper (idb, Dexie). For big caches, offline data and anything above a few hundred kilobytes.
• Versioned shapes: every persisted blob carries a version; loading code migrates or discards old versions. Without it, a renamed field breaks every returning user.
• Cross-tab sync: the storage event fires in other tabs on localStorage writes; BroadcastChannel is the explicit alternative. Decide whether tabs share state or last-writer-wins.
• Export/import turns per-device storage into something portable (this app's Settings page does exactly that); it is also the honest answer to "what if the user clears site data".
• Offline: a service worker with the Cache API (@vite-pwa/nuxt, Workbox) caches the shell and assets; data lives in IndexedDB with a sync queue; background sync and conflict handling are the hard parts. Promise offline only for a defined subset of features.
• Security: anything in localStorage is exposed to XSS; session tokens belong in HttpOnly cookies. Personal data in storage needs a clear-on-logout path.

How it works

Persisted client state that never causes a hydration mismatch (the pattern this app uses):

export function usePersistedState<T extends object>(key: string, init: () => T) {
  // Shared per app, serialisable; on the server it holds the default and that is what renders.
  const state = useState<T>(`persisted:${key}`, init)
  const ready = useState(`persisted-ready:${key}`, () => false)

  if (import.meta.client && !ready.value) {
    const hydrate = () => {
      try {
        const raw = localStorage.getItem(`app:v1:${key}`)
        if (raw) {
          const parsed = JSON.parse(raw) as T & { version?: number }
          state.value = parsed.version === 1 ? parsed : init() // migrate or discard old shapes here
        }
      }
      catch { /* corrupt storage: keep defaults */ }
      ready.value = true
      watch(state, v => localStorage.setItem(`app:v1:${key}`, JSON.stringify(v)), { deep: true })
    }
    const nuxtApp = useNuxtApp()
    // After hydration, so the first client render matches the server HTML.
    if (nuxtApp.isHydrating) nuxtApp.hooks.hookOnce('app:suspense:resolve', hydrate)
    else hydrate()
  }

  return { state, ready }
}

A cookie preference the server can honour, and the URL-state composable with canonical query:

export const useDensity = () => useCookie<'compact' | 'comfortable'>('density', {
  default: () => 'comfortable',
  maxAge: 60 * 60 * 24 * 365,
  sameSite: 'lax',
  secure: true,
})

import { z } from 'zod'

const schema = z.object({
  q: z.string().default(''),
  page: z.coerce.number().int().min(1).default(1),
  sort: z.enum(['recent', 'popular']).default('recent'),
})
type ListQuery = z.infer<typeof schema>
const defaults = schema.parse({})

export function useListQuery() {
  const route = useRoute()
  const router = useRouter()
  const query = computed<ListQuery>(() => schema.parse(route.query))

  function set(patch: Partial<ListQuery>) {
    const next = { ...query.value, ...patch }
    // Canonical: omit defaults so /list and /list?page=1&sort=recent are the same URL.
    const clean = Object.fromEntries(Object.entries(next).filter(([k, v]) => v !== defaults[k as keyof ListQuery]))
    router.replace({ query: clean })
  }

  return { query, set }
}

Cross-tab sync for a draft, and a safe read of a large cache from IndexedDB:

export function useDraft(id: string) {
  const draft = ref('')
  if (import.meta.client) {
    const channel = new BroadcastChannel(`draft:${id}`)
    onMounted(() => { draft.value = localStorage.getItem(`draft:${id}`) ?? '' })
    watchDebounced(draft, (v) => {
      localStorage.setItem(`draft:${id}`, v)
      channel.postMessage(v)
    }, { debounce: 300 })
    channel.onmessage = (e: MessageEvent<string>) => { draft.value = e.data }
    onScopeDispose(() => channel.close())
  }
  return draft
}

Exercise

Be able to say