agent-skills/skills/pinia/references/advanced-ssr.md

name, description

name	description
server-side-rendering	SSR setup, state hydration, and avoiding cross-request state pollution

Server Side Rendering (SSR)

Pinia works with SSR when stores are called at the top of setup, getters, or actions.

Using Nuxt? See the Nuxt integration instead.

Basic Usage

<script setup>
// ✅ Works - pinia knows the app context in setup
const main = useMainStore()
</script>

Using Store Outside setup()

Pass the pinia instance explicitly:

const pinia = createPinia()
const app = createApp(App)
app.use(router)
app.use(pinia)

router.beforeEach((to) => {
  // ✅ Pass pinia for correct SSR context
  const main = useMainStore(pinia)

  if (to.meta.requiresAuth && !main.isLoggedIn) {
    return '/login'
  }
})

serverPrefetch()

Access pinia via this.$pinia:

export default {
  serverPrefetch() {
    const store = useStore(this.$pinia)
    return store.fetchData()
  },
}

onServerPrefetch()

Works normally:

<script setup>
const store = useStore()

onServerPrefetch(async () => {
  await store.fetchData()
})
</script>

State Hydration

Serialize state on server and hydrate on client.

Server Side

Use devalue for XSS-safe serialization:

import devalue from 'devalue'
import { createPinia } from 'pinia'

const pinia = createPinia()
const app = createApp(App)
app.use(router)
app.use(pinia)

// After rendering, state is available
const serializedState = devalue(pinia.state.value)
// Inject into HTML as global variable

Client Side

Hydrate before any useStore() call:

const pinia = createPinia()
const app = createApp(App)
app.use(pinia)

// Hydrate from serialized state (e.g., from window.__pinia)
if (typeof window !== 'undefined') {
  pinia.state.value = JSON.parse(window.__pinia)
}

SSR Examples

• Vitesse template
• vite-plugin-ssr

Key Points

1. Call stores inside functions, not at module scope
2. Pass pinia instance when using stores outside components in SSR
3. Hydrate state before calling any useStore()
4. Use devalue or similar for safe serialization
5. Avoid cross-request state pollution by creating fresh pinia per request