Nuxt · NUXT0085

Initialize VueUse browser storage on mount in SSR apps

Finds VueUse useLocalStorage(), useSessionStorage() and browser-backed useStorage() calls in SSR Nuxt apps that read storage while the page hydrates.
NUXT0085vite-doctor/nuxthydrationwarnSuggestion
vueuse/ssr/require-init-on-mounted-storagesrc/rule-packs/nuxt/rules/vueuse-storage.ts Upstream docs

Run this rule

pnpm nuxt doctor --rules vueuse/ssr/require-init-on-mounted-storage

Why it matters

VueUse reads browser storage synchronously when the composable runs. The server has no browser storage and renders the default value, so a stored value changes the first client render and Vue reports a hydration mismatch. Guarding the call with import.meta.client does not help, because the client branch still runs during hydration.

Pass { initOnMounted: true } so VueUse reads storage after the component mounts, or use useCookie() for state the server must render. A useStorage() call that passes localStorage or sessionStorage explicitly throws on the server before initOnMounted can help, so use useLocalStorage() or useSessionStorage() with { initOnMounted: true } instead. Doctor skips .client files, calls inside onMounted(), apps with ssr: false, and refs that are only read in event handlers, watch callbacks, lifecycle hooks or unrendered computed values. With @vueuse/nuxt's ssrHandlers option, useStorage() without a storage argument uses cookies; Doctor cannot see that option, so it only reports useStorage() without a storage argument in apps without @vueuse/nuxt.

Example

Read stored preferences after mount

Before

<script setup lang="ts">
const granularity = useSessionStorage('plan-granularity', 'month')
</script>

<template>
  <span>{{ granularity }}</span>
</template>

After

<script setup lang="ts">
const granularity = useSessionStorage('plan-granularity', 'month', { initOnMounted: true })
</script>

<template>
  <span>{{ granularity }}</span>
</template>
Copyright © 2026