Best Practices SSR

// composables/bad.ts
// Called at module level - no Nuxt context!
const config = useRuntimeConfig()

export function useMyComposable() {
  return config.public.apiBase
}

// composables/good.ts
export function useMyComposable() {
  // Called inside the composable - has context
  const config = useRuntimeConfig()
  return config.public.apiBase
}

// ✅ Plugin
export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig() // Works
})

// ✅ Middleware
export default defineNuxtRouteMiddleware(() => {
  const route = useRoute() // Works
})

// composables/bad.ts
// This state is SHARED between all requests on server!
const globalState = ref({ user: null })

export function useUser() {
  return globalState
}

// composables/good.ts
export function useUser() {
  // useState creates request-isolated state
  return useState('user', () => ({ user: null }))
}

<script setup>
// localStorage doesn't exist on server!
const theme = localStorage.getItem('theme') || 'light'
</script>

<script setup>
// useCookie works on both server and client
const theme = useCookie('theme', { default: () => 'light' })
</script>

<template>
  <div>{{ Math.random() }}</div>
  <div>{{ new Date().toLocaleTimeString() }}</div>
</template>

<script setup>
// Value is generated once on server, hydrated on client
const randomValue = useState('random', () => Math.random())
</script>

<template>
  <div>{{ randomValue }}</div>
</template>

<template>
  <!-- window doesn't exist on server -->
  <div v-if="window?.innerWidth > 768">Desktop</div>
</template>

<template>
  <!-- CSS media queries work on both -->
  <div class="hidden md:block">Desktop</div>
  <div class="md:hidden">Mobile</div>

  <!-- Or use ClientOnly for JS-dependent rendering -->
  <ClientOnly>
    <ResponsiveComponent />
    <template #fallback>Loading...</template>
  </ClientOnly>
</template>

<script setup>
if (import.meta.client) {
  // Only runs in browser
  window.addEventListener('scroll', handleScroll)
}
</script>

<script setup>
const el = ref<HTMLElement>()

onMounted(() => {
  // Safe - only runs on client after hydration
  el.value?.focus()
  initThirdPartyLib()
})
</script>

<script setup>
onMounted(async () => {
  const { Chart } = await import('chart.js')
  new Chart(canvas.value, config)
})
</script>

<script setup>
if (import.meta.server) {
  // Only runs on server
  const secrets = useRuntimeConfig().apiSecret
}
</script>

<!-- components/ServerData.server.vue -->
<script setup>
// This entire component only runs on server
const data = await fetchSensitiveData()
</script>

<template>
  <div>{{ data }}</div>
</template>

<script setup>
await someAsyncOperation()
const route = useRoute() // May fail - context lost after await
</script>

<script setup>
// Get all composables before any await
const route = useRoute()
const config = useRuntimeConfig()

await someAsyncOperation()
// Now safe to use route and config
</script>

// plugins/analytics.client.ts
export default defineNuxtPlugin(() => {
  // Only runs on client
  initAnalytics()
})

// plugins/server-init.server.ts
export default defineNuxtPlugin(() => {
  // Only runs on server
  initServerConnections()
})

// plugins/api.ts
export default defineNuxtPlugin(() => {
  const api = createApiClient()

  return {
    provide: {
      api,
    },
  }
})

<script setup>
const { $api } = useNuxtApp()
const data = await $api.get('/users')
</script>

<script setup>
import SomeLibrary from 'browser-only-lib' // Breaks SSR
</script>

<script setup>
let library: typeof import('browser-only-lib')

onMounted(async () => {
  library = await import('browser-only-lib')
  library.init()
})
</script>

<template>
  <ClientOnly>
    <BrowserOnlyComponent />
    <template #fallback>
      <div class="skeleton">Loading...</div>
    </template>
  </ClientOnly>
</template>

<script setup>
console.log('Server:', import.meta.server)
console.log('Client:', import.meta.client)
</script>