agent-skills/skills/vue-best-practices/reference/ssr-platform-specific-apis.md

title, impact, impactDescription, type, tags

title	impact	impactDescription	type	tags
Guard Platform-Specific APIs in Universal SSR Code	HIGH	Accessing browser-only APIs on server causes crashes; Node.js APIs fail in browser	gotcha	vue3 ssr browser-api nodejs universal isomorphic server-side-rendering

Guard Platform-Specific APIs in Universal SSR Code

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.

Universal/isomorphic code must guard platform-specific API access or use libraries that work on both platforms.

Task Checklist

• Never access window, document, navigator in setup() or created()
• Move browser API access to onMounted() lifecycle hook
• Use typeof window !== 'undefined' guard when needed outside lifecycle
• Use cross-platform libraries for common functionality (fetch, storage)
• Use Nuxt's process.client / process.server guards in Nuxt projects

Common Browser APIs That Break SSR

API	Node.js Behavior
window	ReferenceError: window is not defined
document	ReferenceError: document is not defined
localStorage / sessionStorage	ReferenceError
navigator	ReferenceError
location	ReferenceError
history	ReferenceError
alert / confirm / prompt	ReferenceError
requestAnimationFrame	ReferenceError
IntersectionObserver	ReferenceError
ResizeObserver	ReferenceError

Incorrect - Crashes on Server:

// WRONG: These run during setup/SSR - crashes in Node.js
const width = ref(window.innerWidth)
const theme = localStorage.getItem('theme')
const userAgent = navigator.userAgent

<script setup>
import { ref } from 'vue'

// WRONG: Runs on server, crashes
const scrollY = ref(window.scrollY)

// WRONG: document doesn't exist on server
document.title = 'My Page'
</script>

Correct - Use onMounted:

<script setup>
import { ref, onMounted, onUnmounted } from 'vue'

// Safe defaults that work on server
const width = ref(0)
const theme = ref('light')
const scrollY = ref(0)

onMounted(() => {
  // Browser APIs only accessed after mount (client-only)
  width.value = window.innerWidth
  theme.value = localStorage.getItem('theme') || 'light'
  scrollY.value = window.scrollY

  // Event listeners safe in mounted
  window.addEventListener('resize', handleResize)
  window.addEventListener('scroll', handleScroll)
})

onUnmounted(() => {
  window.removeEventListener('resize', handleResize)
  window.removeEventListener('scroll', handleScroll)
})

function handleResize() {
  width.value = window.innerWidth
}

function handleScroll() {
  scrollY.value = window.scrollY
}
</script>

Correct - Guard with typeof:

// When you need to check outside lifecycle hooks
function getStoredValue(key, defaultValue) {
  if (typeof window !== 'undefined' && window.localStorage) {
    return localStorage.getItem(key) ?? defaultValue
  }
  return defaultValue
}

// Composable with SSR awareness
export function useMediaQuery(query) {
  const matches = ref(false)

  // Only run on client
  if (typeof window !== 'undefined') {
    const mediaQuery = window.matchMedia(query)
    matches.value = mediaQuery.matches

    // Setup listener in lifecycle
    onMounted(() => {
      const handler = (e) => { matches.value = e.matches }
      mediaQuery.addEventListener('change', handler)
      onUnmounted(() => mediaQuery.removeEventListener('change', handler))
    })
  }

  return matches
}

Nuxt.js Guards

<script setup>
// Nuxt provides process.client and process.server
if (process.client) {
  // Only runs in browser
  window.analytics.track('page_view')
}

if (process.server) {
  // Only runs on server
  console.log('Rendering on server')
}
</script>

<template>
  <!-- ClientOnly component for client-only rendering -->
  <ClientOnly>
    <BrowserOnlyChart :data="chartData" />
    <template #fallback>
      <ChartSkeleton />
    </template>
  </ClientOnly>
</template>

Cross-Platform Libraries

Use libraries that abstract platform differences:

// Fetch - works in both Node.js 18+ and browsers
const response = await fetch('/api/data')

// For older Node.js, use node-fetch or axios
import axios from 'axios'
const { data } = await axios.get('/api/data')

// Universal cookie handling
import Cookies from 'js-cookie' // Client only
import { parse } from 'cookie' // Works both

// In Nuxt, use useCookie()
const token = useCookie('auth-token')

Common Node.js APIs That Break in Browser

API	Browser Behavior
fs	Module not found
path	Module not found
process (full)	Undefined or limited
Buffer	Undefined (unless polyfilled)
__dirname / __filename	Undefined
require()	Undefined in ES modules

Incorrect:

// WRONG: Node.js APIs in universal code
import fs from 'fs'
const config = JSON.parse(fs.readFileSync('./config.json'))

Correct - Separate Server Code:

// server/utils.js - Server-only file
import fs from 'fs'
export function loadConfig() {
  return JSON.parse(fs.readFileSync('./config.json'))
}

// app.js - Universal code uses API instead
const config = await fetch('/api/config').then(r => r.json())

Environment Detection Utility

// utils/environment.js
export const isClient = typeof window !== 'undefined'
export const isServer = !isClient

export const isBrowser = isClient && typeof document !== 'undefined'
export const isNode = typeof process !== 'undefined' &&
                      process.versions?.node != null

// Usage
import { isClient, isServer } from '@/utils/environment'

if (isClient) {
  // Browser-specific code
}

Third-Party Library Issues

Some libraries auto-access browser APIs on import:

// WRONG: Library accesses window on import
import SomeChartLibrary from 'some-chart-library'
// ^ Crashes on server if library does: const x = window.something

Correct - Dynamic Import:

<script setup>
import { defineAsyncComponent } from 'vue'

// Dynamic import only loads on client
const Chart = defineAsyncComponent(() =>
  import('some-chart-library').then(m => m.ChartComponent)
)
</script>

<template>
  <ClientOnly>
    <Chart :data="data" />
  </ClientOnly>
</template>

Reference

• Vue.js SSR - Platform-Specific APIs
• Nuxt ClientOnly Component
• MDN: Web APIs