Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
viteSSR (default)
✓ import viteSSR from 'vite-ssr'
✗ const viteSSR = require('vite-ssr')
ESM-only; CJS require will fail. Use 'vite-ssr/vue' or 'vite-ssr/react' for better type inference.
viteSSR plugin
✓ import viteSSR from 'vite-ssr/plugin.js'
✗ import { viteSSR } from 'vite-ssr/plugin.js'
Plugin is a default export, not named. Must use Vite config's plugins array.
viteSSR from framework subpath
✓ import viteSSR from 'vite-ssr/vue'
✗ import { viteSSR } from 'vite-ssr/vue'
Framework-specific entry points are default exports for better type inference.
viteSSR type
✓ import type { ViteSSRContext } from 'vite-ssr'
✗ import { ViteSSRContext } from 'vite-ssr'
Type-only import to avoid runtime side effects.
Shows minimal setup for Vue SSR with Vite: plugin config, entry file with router and SSR hook.
// vite.config.js
import vue from '@vitejs/plugin-vue'
import viteSSR from 'vite-ssr/plugin.js'
export default {
plugins: [viteSSR(), vue()],
}
// src/main.js
import App from './App.vue'
import { createRouter, createMemoryHistory, createWebHistory } from 'vue-router'
import viteSSR from 'vite-ssr/vue'
const routes = [
{ path: '/', component: () => import('./Home.vue') },
]
export default viteSSR(App, { routes }, (context) => {
const { app, router, initialState } = context
// Optional: Pinia store setup
// const pinia = createPinia()
// app.use(pinia)
// if (import.meta.env.SSR) {
// initialState.pinia = pinia.state.value
// } else {
// pinia.state.value = initialState.pinia || {}
// }
})
Debug
Known issues
breakingIn v0.15.0 the `url` object in SSR context changed from `Location` type to `URL` type.fixUpdate code that accesses `url` properties (e.g., `url.search` vs `url.searchParams`).
affects: >=0.15.0 <0.16.0
breakingv0.17.0 dropped support for Vite 3; requires Vite 4+.fixUpgrade Vite to version 4, and migrate Vite config as per Vite migration guide.
affects: >=0.17.0
deprecatedreact-router-dom v5 support is deprecated; migrate to v6.fixUpdate package.json: replace 'react-router-config' and 'react-router-dom@5' with 'react-router-dom@6'. Adjust route config shape.
affects: >=0.16.0 <0.17.0
gotchaThe plugin must be imported as `import viteSSR from 'vite-ssr/plugin.js'` (default export). Using named import causes runtime error.fixUse default import syntax.
affects: all
gotchaState serialization may fail if data contains already escaped characters (e.g., newlines). Fixed in v0.14.2.fixUpgrade to v0.14.2+ or manually sanitize state values.
affects: <0.14.2
breakingIn v0.14.0 state serialization changed to JSON, breaking custom serialization logic.fixRemove custom serializer functions; data is now JSON-serialized automatically.
affects: >=0.14.0 <0.15.0
Errors
Common errors & fixes
Cannot find module 'vite-ssr' or its corresponding type declarations.
Using CommonJS require instead of ESM import.
fixReplace `const viteSSR = require('vite-ssr')` with `import viteSSR from 'vite-ssr'` in a file with .js or .mjs extension, and ensure `"type": "module"` in package.json. Error: [vite] Internal server error: __DEV__ is not defined.
__DEV__ global conflicts with Vite 4's define; fixed in v0.17.2.
fixUpgrade to vite-ssr@0.17.2 or later.
TypeError: Cannot destructure property 'app' of 'context' as it is undefined.
Using named export `{ viteSSR }` from plugin.js instead of default export.
fixChange import to `import viteSSR from 'vite-ssr/plugin.js'` (default export).
Error: [vite-ssr] The 'url' property is missing or invalid.
Accessing `url` properties assuming Location type after v0.15.0 breaking change.
fixUpdate code to use URL API: e.g., `url.searchParams.get('q')` instead of `url.search`. Warning: React version mismatch. Expected 17, got 18.
vite-ssr peer dependency requires React 17; React 18 is not officially supported.
fixDowngrade React to 17 or use a compatible fork; check for updates on v0.18.0.
Audit
Dependencies
viterequiredPeer dependency; the library is a Vite plugin and needs Vite 4+
@vitejs/plugin-reactoptionalPeer dependency for React projects using Vite 4
@vitejs/plugin-vueoptionalPeer dependency for Vue projects using Vite 4
vue-routeroptionalPeer dependency for Vue SSR projects
react-router-domoptionalPeer dependency for React SSR projects