1# Suspense SSR Hydration Issues and Workarounds
2 
3## Rule
4 
5`<Suspense>` has known issues with SSR hydration, particularly with async components. During initial hydration, Suspense may not properly include child components within its "cloak of suspense," leading to hydration mismatches, flickering, or runtime crashes.
6 
7## Why This Matters
8 
9In SSR applications, hydration mismatches cause:
10- Visual flickering as the client re-renders
11- Loss of state in affected components
12- Console warnings in development (silent failures in production)
13- Potential runtime crashes in edge cases
14- Poor user experience, especially on slower networks
15 
16## Bad Code
17 
18```vue
19<template>
20  <!-- Async component directly in Suspense can fail hydration -->
21  <Suspense>
22    <AsyncDashboard />
23    <template #fallback>
24      Loading...
25    </template>
26  </Suspense>
27</template>
28 
29<script setup>
30import { defineAsyncComponent } from 'vue'
31 
32const AsyncDashboard = defineAsyncComponent(
33  () => import('./Dashboard.vue')
34)
35</script>
36```
37 
38## Good Code
39 
40### Solution 1: Wrap Async Components with Suspense
41 
42```vue
43<template>
44  <!-- Each async component wrapped in its own Suspense -->
45  <div class="dashboard">
46    <Suspense>
47      <AsyncHeader />
48      <template #fallback><HeaderSkeleton /></template>
49    </Suspense>
50 
51    <Suspense>
52      <AsyncContent />
53      <template #fallback><ContentSkeleton /></template>
54    </Suspense>
55  </div>
56</template>
57```
58 
59### Solution 2: Use ClientOnly Wrapper (Nuxt/SSR Frameworks)
60 
61```vue
62<template>
63  <!-- Prevent SSR for problematic async components -->
64  <ClientOnly>
65    <Suspense>
66      <AsyncDashboard />
67      <template #fallback>
68        Loading dashboard...
69      </template>
70    </Suspense>
71 
72    <template #fallback>
73      <DashboardSkeleton />
74    </template>
75  </ClientOnly>
76</template>
77```
78 
79### Solution 3: Prefetch with Proper Stale Time (with TanStack Query)
80 
81```vue
82<script setup>
83import { useQuery, useQueryClient } from '@tanstack/vue-query'
84 
85// IMPORTANT: All useQuery calls must be BEFORE any await
86const { data, suspense } = useQuery({
87  queryKey: ['dashboard'],
88  queryFn: fetchDashboardData,
89  staleTime: 1000 * 60 * 5, // 5 minutes - prevents refetch after hydration
90})
91 
92// Wait for suspense AFTER all useQuery calls
93await suspense()
94 
95// Now safe to use data
96</script>
97```
98 
99### Solution 4: Handle Hydration Errors Gracefully
100 
101```vue
102<script setup>
103import { ref, onErrorCaptured, onMounted } from 'vue'
104 
105const hydrationError = ref(false)
106const isClient = ref(false)
107 
108onMounted(() => {
109  isClient.value = true
110})
111 
112onErrorCaptured((err) => {
113  if (err.message?.includes('hydration')) {
114    hydrationError.value = true
115    return false
116  }
117})
118</script>
119 
120<template>
121  <div v-if="hydrationError" class="hydration-recovery">
122    <!-- Force client-only re-render -->
123    <Suspense v-if="isClient">
124      <AsyncContent />
125      <template #fallback>Recovering...</template>
126    </Suspense>
127  </div>
128 
129  <Suspense v-else>
130    <AsyncContent />
131    <template #fallback>Loading...</template>
132  </Suspense>
133</template>
134```
135 
136## Common SSR + Suspense Issues
137 
138| Issue | Cause | Solution |
139|-------|-------|----------|
140| Hydration mismatch | Async chunk not loaded in time | Wrap with Suspense or use ClientOnly |
141| Empty flash on Safari | Slow chunk loading | Preload critical chunks, use skeleton |
142| useQuery after await error | Vue context lost after await | Put all useQuery calls before any await |
143| Immediate refetch after hydration | staleTime too low | Set appropriate staleTime value |
144 
145## Key Points
146 
1471. Suspense + SSR has known edge cases - test thoroughly
1482. Safari has slower chunk loading that triggers more hydration issues
1493. With data-fetching libraries, ensure queries are set up before awaiting suspense
1504. Consider ClientOnly wrappers for non-critical async content
1515. Set appropriate staleTime to prevent unnecessary refetches after hydration
1526. Use skeleton screens that match server-rendered content structure
153 
154## References
155 
156- [Vue.js Suspense Documentation](https://vuejs.org/guide/built-ins/suspense)
157- [Vue Issue #6638 - Suspense hydration](https://github.com/vuejs/core/issues/6638)
158- [Vue Issue #7672 - defineAsyncComponent SSR](https://github.com/vuejs/core/issues/7672)
159- [TanStack Query SSR Discussion](https://github.com/TanStack/query/discussions/4870)
160