1---
2name: ssr-best-practices
3description: Avoiding SSR context leaks, hydration mismatches, and proper composable usage
4---
5 
6# SSR Best Practices
7 
8Patterns for avoiding common SSR pitfalls: context leaks, hydration mismatches, and composable errors.
9 
10## The "Nuxt Instance Unavailable" Error
11 
12This error occurs when calling Nuxt composables outside the proper context.
13 
14### ❌ Wrong: Composable Outside Setup
15 
16```ts
17// composables/bad.ts
18// Called at module level - no Nuxt context!
19const config = useRuntimeConfig()
20 
21export function useMyComposable() {
22  return config.public.apiBase
23}
24```
25 
26### ✅ Correct: Composable Inside Function
27 
28```ts
29// composables/good.ts
30export function useMyComposable() {
31  // Called inside the composable - has context
32  const config = useRuntimeConfig()
33  return config.public.apiBase
34}
35```
36 
37### Valid Contexts for Composables
38 
39Nuxt composables work in:
40- `<script setup>` blocks
41- `setup()` function
42- `defineNuxtPlugin()` callbacks
43- `defineNuxtRouteMiddleware()` callbacks
44 
45```ts
46// ✅ Plugin
47export default defineNuxtPlugin(() => {
48  const config = useRuntimeConfig() // Works
49})
50 
51// ✅ Middleware
52export default defineNuxtRouteMiddleware(() => {
53  const route = useRoute() // Works
54})
55```
56 
57## Avoid State Leaks Between Requests
58 
59### ❌ Wrong: Module-level State
60 
61```ts
62// composables/bad.ts
63// This state is SHARED between all requests on server!
64const globalState = ref({ user: null })
65 
66export function useUser() {
67  return globalState
68}
69```
70 
71### ✅ Correct: Use useState
72 
73```ts
74// composables/good.ts
75export function useUser() {
76  // useState creates request-isolated state
77  return useState('user', () => ({ user: null }))
78}
79```
80 
81### Why This Matters
82 
83On the server, module-level state persists across requests, causing:
84- Data leaking between users
85- Security vulnerabilities
86- Memory leaks
87 
88## Hydration Mismatch Prevention
89 
90Hydration mismatches occur when server HTML differs from client render.
91 
92### ❌ Wrong: Browser APIs in Setup
93 
94```vue
95<script setup>
96// localStorage doesn't exist on server!
97const theme = localStorage.getItem('theme') || 'light'
98</script>
99```
100 
101### ✅ Correct: Use SSR-safe Alternatives
102 
103```vue
104<script setup>
105// useCookie works on both server and client
106const theme = useCookie('theme', { default: () => 'light' })
107</script>
108```
109 
110### ❌ Wrong: Random/Time-based Values
111 
112```vue
113<template>
114  <div>{{ Math.random() }}</div>
115  <div>{{ new Date().toLocaleTimeString() }}</div>
116</template>
117```
118 
119### ✅ Correct: Use useState for Consistency
120 
121```vue
122<script setup>
123// Value is generated once on server, hydrated on client
124const randomValue = useState('random', () => Math.random())
125</script>
126 
127<template>
128  <div>{{ randomValue }}</div>
129</template>
130```
131 
132### ❌ Wrong: Conditional Rendering on Client State
133 
134```vue
135<template>
136  <!-- window doesn't exist on server -->
137  <div v-if="window?.innerWidth > 768">Desktop</div>
138</template>
139```
140 
141### ✅ Correct: Use CSS or ClientOnly
142 
143```vue
144<template>
145  <!-- CSS media queries work on both -->
146  <div class="hidden md:block">Desktop</div>
147  <div class="md:hidden">Mobile</div>
148 
149  <!-- Or use ClientOnly for JS-dependent rendering -->
150  <ClientOnly>
151    <ResponsiveComponent />
152    <template #fallback>Loading...</template>
153  </ClientOnly>
154</template>
155```
156 
157## Browser-only Code
158 
159### Use `import.meta.client`
160 
161```vue
162<script setup>
163if (import.meta.client) {
164  // Only runs in browser
165  window.addEventListener('scroll', handleScroll)
166}
167</script>
168```
169 
170### Use `onMounted` for DOM Access
171 
172```vue
173<script setup>
174const el = ref<HTMLElement>()
175 
176onMounted(() => {
177  // Safe - only runs on client after hydration
178  el.value?.focus()
179  initThirdPartyLib()
180})
181</script>
182```
183 
184### Dynamic Imports for Browser Libraries
185 
186```vue
187<script setup>
188onMounted(async () => {
189  const { Chart } = await import('chart.js')
190  new Chart(canvas.value, config)
191})
192</script>
193```
194 
195## Server-only Code
196 
197### Use `import.meta.server`
198 
199```vue
200<script setup>
201if (import.meta.server) {
202  // Only runs on server
203  const secrets = useRuntimeConfig().apiSecret
204}
205</script>
206```
207 
208### Server Components
209 
210```vue
211<!-- components/ServerData.server.vue -->
212<script setup>
213// This entire component only runs on server
214const data = await fetchSensitiveData()
215</script>
216 
217<template>
218  <div>{{ data }}</div>
219</template>
220```
221 
222## Async Composable Patterns
223 
224### ❌ Wrong: Await Before Composable
225 
226```vue
227<script setup>
228await someAsyncOperation()
229const route = useRoute() // May fail - context lost after await
230</script>
231```
232 
233### ✅ Correct: Get Context First
234 
235```vue
236<script setup>
237// Get all composables before any await
238const route = useRoute()
239const config = useRuntimeConfig()
240 
241await someAsyncOperation()
242// Now safe to use route and config
243</script>
244```
245 
246## Plugin Best Practices
247 
248### Client-only Plugins
249 
250```ts
251// plugins/analytics.client.ts
252export default defineNuxtPlugin(() => {
253  // Only runs on client
254  initAnalytics()
255})
256```
257 
258### Server-only Plugins
259 
260```ts
261// plugins/server-init.server.ts
262export default defineNuxtPlugin(() => {
263  // Only runs on server
264  initServerConnections()
265})
266```
267 
268### Provide/Inject Pattern
269 
270```ts
271// plugins/api.ts
272export default defineNuxtPlugin(() => {
273  const api = createApiClient()
274 
275  return {
276    provide: {
277      api,
278    },
279  }
280})
281```
282 
283```vue
284<script setup>
285const { $api } = useNuxtApp()
286const data = await $api.get('/users')
287</script>
288```
289 
290## Third-party Library Integration
291 
292### ❌ Wrong: Import at Top Level
293 
294```vue
295<script setup>
296import SomeLibrary from 'browser-only-lib' // Breaks SSR
297</script>
298```
299 
300### ✅ Correct: Dynamic Import
301 
302```vue
303<script setup>
304let library: typeof import('browser-only-lib')
305 
306onMounted(async () => {
307  library = await import('browser-only-lib')
308  library.init()
309})
310</script>
311```
312 
313### Use ClientOnly Component
314 
315```vue
316<template>
317  <ClientOnly>
318    <BrowserOnlyComponent />
319    <template #fallback>
320      <div class="skeleton">Loading...</div>
321    </template>
322  </ClientOnly>
323</template>
324```
325 
326## Debugging SSR Issues
327 
328### Check Rendering Context
329 
330```vue
331<script setup>
332console.log('Server:', import.meta.server)
333console.log('Client:', import.meta.client)
334</script>
335```
336 
337### Use Nuxt DevTools
338 
339DevTools shows payload data and hydration state.
340 
341### Common Error Messages
342 
343| Error | Cause |
344|-------|-------|
345| "Nuxt instance unavailable" | Composable called outside setup context |
346| "Hydration mismatch" | Server/client HTML differs |
347| "window is not defined" | Browser API used during SSR |
348| "document is not defined" | DOM access during SSR |
349 
350<!-- 
351Source references:
352- https://nuxt.com/docs/guide/concepts/auto-imports#vue-and-nuxt-composables
353- https://nuxt.com/docs/guide/best-practices/hydration
354- https://nuxt.com/docs/getting-started/state-management#best-practices
355-->
356