1---
2title: Guard Platform-Specific APIs in Universal SSR Code
3impact: HIGH
4impactDescription: Accessing browser-only APIs on server causes crashes; Node.js APIs fail in browser
5type: gotcha
6tags: [vue3, ssr, browser-api, nodejs, universal, isomorphic, server-side-rendering]
7---
8 
9# Guard Platform-Specific APIs in Universal SSR Code
10 
11**Impact: HIGH** - SSR applications run the same code on both server (Node.js) and client (browser). Browser APIs like `window`, `document`, and `localStorage` don't exist in Node.js and will throw `ReferenceError`. Similarly, Node.js APIs like `fs` and `process` aren't available in browsers.
12 
13Universal/isomorphic code must guard platform-specific API access or use libraries that work on both platforms.
14 
15## Task Checklist
16 
17- [ ] Never access `window`, `document`, `navigator` in `setup()` or `created()`
18- [ ] Move browser API access to `onMounted()` lifecycle hook
19- [ ] Use `typeof window !== 'undefined'` guard when needed outside lifecycle
20- [ ] Use cross-platform libraries for common functionality (fetch, storage)
21- [ ] Use Nuxt's `process.client` / `process.server` guards in Nuxt projects
22 
23## Common Browser APIs That Break SSR
24 
25| API | Node.js Behavior |
26|-----|-----------------|
27| `window` | `ReferenceError: window is not defined` |
28| `document` | `ReferenceError: document is not defined` |
29| `localStorage` / `sessionStorage` | `ReferenceError` |
30| `navigator` | `ReferenceError` |
31| `location` | `ReferenceError` |
32| `history` | `ReferenceError` |
33| `alert` / `confirm` / `prompt` | `ReferenceError` |
34| `requestAnimationFrame` | `ReferenceError` |
35| `IntersectionObserver` | `ReferenceError` |
36| `ResizeObserver` | `ReferenceError` |
37 
38**Incorrect - Crashes on Server:**
39```javascript
40// WRONG: These run during setup/SSR - crashes in Node.js
41const width = ref(window.innerWidth)
42const theme = localStorage.getItem('theme')
43const userAgent = navigator.userAgent
44```
45 
46```vue
47<script setup>
48import { ref } from 'vue'
49 
50// WRONG: Runs on server, crashes
51const scrollY = ref(window.scrollY)
52 
53// WRONG: document doesn't exist on server
54document.title = 'My Page'
55</script>
56```
57 
58**Correct - Use onMounted:**
59```vue
60<script setup>
61import { ref, onMounted, onUnmounted } from 'vue'
62 
63// Safe defaults that work on server
64const width = ref(0)
65const theme = ref('light')
66const scrollY = ref(0)
67 
68onMounted(() => {
69  // Browser APIs only accessed after mount (client-only)
70  width.value = window.innerWidth
71  theme.value = localStorage.getItem('theme') || 'light'
72  scrollY.value = window.scrollY
73 
74  // Event listeners safe in mounted
75  window.addEventListener('resize', handleResize)
76  window.addEventListener('scroll', handleScroll)
77})
78 
79onUnmounted(() => {
80  window.removeEventListener('resize', handleResize)
81  window.removeEventListener('scroll', handleScroll)
82})
83 
84function handleResize() {
85  width.value = window.innerWidth
86}
87 
88function handleScroll() {
89  scrollY.value = window.scrollY
90}
91</script>
92```
93 
94**Correct - Guard with typeof:**
95```javascript
96// When you need to check outside lifecycle hooks
97function getStoredValue(key, defaultValue) {
98  if (typeof window !== 'undefined' && window.localStorage) {
99    return localStorage.getItem(key) ?? defaultValue
100  }
101  return defaultValue
102}
103 
104// Composable with SSR awareness
105export function useMediaQuery(query) {
106  const matches = ref(false)
107 
108  // Only run on client
109  if (typeof window !== 'undefined') {
110    const mediaQuery = window.matchMedia(query)
111    matches.value = mediaQuery.matches
112 
113    // Setup listener in lifecycle
114    onMounted(() => {
115      const handler = (e) => { matches.value = e.matches }
116      mediaQuery.addEventListener('change', handler)
117      onUnmounted(() => mediaQuery.removeEventListener('change', handler))
118    })
119  }
120 
121  return matches
122}
123```
124 
125## Nuxt.js Guards
126 
127```vue
128<script setup>
129// Nuxt provides process.client and process.server
130if (process.client) {
131  // Only runs in browser
132  window.analytics.track('page_view')
133}
134 
135if (process.server) {
136  // Only runs on server
137  console.log('Rendering on server')
138}
139</script>
140```
141 
142```vue
143<template>
144  <!-- ClientOnly component for client-only rendering -->
145  <ClientOnly>
146    <BrowserOnlyChart :data="chartData" />
147    <template #fallback>
148      <ChartSkeleton />
149    </template>
150  </ClientOnly>
151</template>
152```
153 
154## Cross-Platform Libraries
155 
156Use libraries that abstract platform differences:
157 
158```javascript
159// Fetch - works in both Node.js 18+ and browsers
160const response = await fetch('/api/data')
161 
162// For older Node.js, use node-fetch or axios
163import axios from 'axios'
164const { data } = await axios.get('/api/data')
165```
166 
167```javascript
168// Universal cookie handling
169import Cookies from 'js-cookie' // Client only
170import { parse } from 'cookie' // Works both
171 
172// In Nuxt, use useCookie()
173const token = useCookie('auth-token')
174```
175 
176## Common Node.js APIs That Break in Browser
177 
178| API | Browser Behavior |
179|-----|-----------------|
180| `fs` | Module not found |
181| `path` | Module not found |
182| `process` (full) | Undefined or limited |
183| `Buffer` | Undefined (unless polyfilled) |
184| `__dirname` / `__filename` | Undefined |
185| `require()` | Undefined in ES modules |
186 
187**Incorrect:**
188```javascript
189// WRONG: Node.js APIs in universal code
190import fs from 'fs'
191const config = JSON.parse(fs.readFileSync('./config.json'))
192```
193 
194**Correct - Separate Server Code:**
195```javascript
196// server/utils.js - Server-only file
197import fs from 'fs'
198export function loadConfig() {
199  return JSON.parse(fs.readFileSync('./config.json'))
200}
201 
202// app.js - Universal code uses API instead
203const config = await fetch('/api/config').then(r => r.json())
204```
205 
206## Environment Detection Utility
207 
208```javascript
209// utils/environment.js
210export const isClient = typeof window !== 'undefined'
211export const isServer = !isClient
212 
213export const isBrowser = isClient && typeof document !== 'undefined'
214export const isNode = typeof process !== 'undefined' &&
215                      process.versions?.node != null
216 
217// Usage
218import { isClient, isServer } from '@/utils/environment'
219 
220if (isClient) {
221  // Browser-specific code
222}
223```
224 
225## Third-Party Library Issues
226 
227Some libraries auto-access browser APIs on import:
228 
229```javascript
230// WRONG: Library accesses window on import
231import SomeChartLibrary from 'some-chart-library'
232// ^ Crashes on server if library does: const x = window.something
233```
234 
235**Correct - Dynamic Import:**
236```vue
237<script setup>
238import { defineAsyncComponent } from 'vue'
239 
240// Dynamic import only loads on client
241const Chart = defineAsyncComponent(() =>
242  import('some-chart-library').then(m => m.ChartComponent)
243)
244</script>
245 
246<template>
247  <ClientOnly>
248    <Chart :data="data" />
249  </ClientOnly>
250</template>
251```
252 
253## Reference
254- [Vue.js SSR - Platform-Specific APIs](https://vuejs.org/guide/scaling-up/ssr.html#access-to-platform-specific-apis)
255- [Nuxt ClientOnly Component](https://nuxt.com/docs/api/components/client-only)
256- [MDN: Web APIs](https://developer.mozilla.org/en-US/docs/Web/API)
257