@nuxt/docs-nightly 4.0.2-29220245.c4317e05 → 4.0.2-29224087.d4d04725

package/2.guide/5.best-practices/hydration.md

@@ -0,0 +1,188 @@
+---
+navigation.title: 'Nuxt and hydration'
+title: Nuxt and hydration
+description: 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:
+
+![Screenshot of Vue hydration mismatch warning in the browser console](/assets/docs/best-practices/vue-console-hydration.png)
+
+# Common reasons
+
+## Browser-only APIs in Server Context
+
+**Problem**: Using browser-specific APIs during server-side rendering.
+
+```html
+<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`](/docs/api/composables/use-cookie):
+
+```html
+<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.
+
+```html
+<template>
+  <div>{{ Math.random() }}</div>
+</template>
+```
+
+**Solution**: Use SSR-friendly state:
+
+```html
+<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.
+
+```html
+<template>
+  <div v-if="window?.innerWidth > 768">
+    Desktop content
+  </div>
+</template>
+```
+
+**Solution**: Use media queries or handle it client-side:
+
+```html
+<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).
+
+```html
+<script setup>
+if (import.meta.client) {
+    const { default: SomeBrowserLibrary } = await import('browser-only-lib')
+    SomeBrowserLibrary.init()
+}
+</script>
+```
+
+**Solution**: Initialise libraries after hydration has completed:
+
+```html
+<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.
+
+```html
+<template>
+  <div>{{ greeting }}</div>
+</template>
+
+<script setup>
+const hour = new Date().getHours()
+const greeting = hour < 12 ? 'Good morning' : 'Good afternoon'
+</script>
+```
+
+**Solution**: Use [`NuxtTime`](/docs/api/components/nuxt-time) component or handle it client-side:
+
+```html
+<template>
+  <div>
+    <NuxtTime :date="new Date()" format="HH:mm" />
+  </div>
+</template>
+```
+
+```html
+<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`](/docs/api/composables/use-fetch), [`useAsyncData`](/docs/api/composables/use-async-data), [`useState`](/docs/api/composables/use-state)
+2. **Wrap client-only code**: Use [`ClientOnly`](/docs/api/components/client-only) 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`
+
+::tip
+You can read the [Vue documentation on SSR hydration mismatch](https://vuejs.org/guide/scaling-up/ssr.html#hydration-mismatch) for a better understanding of hydration.
+::

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt/docs-nightly",
-  "version": "4.0.2-29220245.c4317e05",
+  "version": "4.0.2-29224087.d4d04725",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nuxt/nuxt.git",