Nuxt · Hydration & SSR

NUXT0085Initialize 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.

Why it happens

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.

Fix

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>

Verify the fix

Run only this rule after editing so the report stays focused on the diagnostic you are closing:

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