Nuxt and hydration

Why fixing hydration issues is important

When developing, you may face hydration issues. Don't ignore those warnings.

Why is it important to fix them?

Hydration mismatches are not just warnings - they are indicators of serious problems that can break your application:

Performance Impact

  • Increased time to interactive: Hydration errors force Vue to re-render the entire component tree, which will increase the time for your Nuxt app to become interactive
  • Poor user experience: Users may see content flashing or unexpected layout shifts

Functionality Issues

  • Broken interactivity: Event listeners may not attach properly, leaving buttons and forms non-functional
  • State inconsistencies: Application state can become out of sync between what the user sees and what the application thinks is rendered
  • SEO problems: Search engines may index different content than what users actually see

How to detect them

Development Console Warnings

Vue will log hydration mismatch warnings in the browser console during development:

Common reasons

Browser-only APIs in Server Context

Problem: Using browser-specific APIs during server-side rendering.

<template>
  <div>User preference: {{ userTheme }}</div>
</template>

<script setup>
// This will cause hydration mismatch!
// localStorage doesn't exist on the server!
const userTheme = localStorage.getItem('theme') || 'light'
</script>

Solution: You can use useCookie:

<template>
  <div>User preference: {{ userTheme }}</div>
</template>

<script setup>
// This works on both server and client
const userTheme = useCookie('theme', { default: () => 'light' })
</script>

Inconsistent Data

Problem: Different data between server and client.

<template>
  <div>{{ Math.random() }}</div>
</template>

Solution: Use SSR-friendly state:

<template>
  <div>{{ state }}</div>
</template>

<script setup>
const state = useState('random', () => Math.random())
</script>

Conditional Rendering Based on Client State

Problem: Using client-only conditions during SSR.

<template>
  <div v-if="window?.innerWidth > 768">
    Desktop content
  </div>
</template>

Solution: Use media queries or handle it client-side:

<template>
  <div class="responsive-content">
    <div class="hidden md:block">Desktop content</div>
    <div class="md:hidden">Mobile content</div>
  </div>
</template>

Third-party Libraries with Side Effects

Problem: Libraries that modify the DOM or have browser dependencies (this happens a LOT with tag managers).

<script setup>
if (import.meta.client) {
    const { default: SomeBrowserLibrary } = await import('browser-only-lib')
    SomeBrowserLibrary.init()
}
</script>

Solution: Initialise libraries after hydration has completed:

<script setup>
onMounted(async () => {
  const { default: SomeBrowserLibrary } = await import('browser-only-lib')
  SomeBrowserLibrary.init()
})
</script>

Dynamic Content Based on Time

Problem: Content that changes based on current time.

<template>
  <div>{{ greeting }}</div>
</template>

<script setup>
const hour = new Date().getHours()
const greeting = hour < 12 ? 'Good morning' : 'Good afternoon'
</script>

Solution: Use NuxtTime component or handle it client-side:

<template>
  <div>
    <NuxtTime :date="new Date()" format="HH:mm" />
  </div>
</template>

<template>
  <div>
    <ClientOnly>
      {{ greeting }}
      <template #fallback>
        Hello!
      </template>
    </ClientOnly>
  </div>
</template>

<script setup>
const greeting = ref('Hello!')

onMounted(() => {
  const hour = new Date().getHours()
  greeting.value = hour < 12 ? 'Good morning' : 'Good afternoon'
})
</script>

In summary

  1. Use SSR-friendly composables: useFetch, useAsyncData, useState
  2. Wrap client-only code: Use ClientOnly component for browser-specific content
  3. Consistent data sources: Ensure server and client uses the same data
  4. Avoid side effects in setup: Move browser-dependent code to onMounted
You can read the Vue documentation on SSR hydration mismatch for a better understanding of hydration.