Vite SSR

0.17.2 verified Mon Apr 27 auth: no javascript

vite-ssr is a lightweight library for server-side rendering with Vite, supporting Vue and React. Current stable version is 0.17.2, released in late 2022. It abstracts SSR complexity while staying unopinionated about routing and API logic, offering lightning-fast HMR even in SSR mode. Unlike heavier frameworks like Next.js or Nuxt, it integrates directly with Vite's plugin ecosystem and can be deployed to Node.js, serverless platforms (Vercel, Netlify), or edge runtimes like Cloudflare Workers. The package ships TypeScript types and requires Vite 4+.

Common errors

error Cannot find module 'vite-ssr' or its corresponding type declarations. ↓

cause Using CommonJS require instead of ESM import.

fix

Replace 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 Error: [vite] Internal server error: __DEV__ is not defined. ↓

cause __DEV__ global conflicts with Vite 4's define; fixed in v0.17.2.

fix

Upgrade to vite-ssr@0.17.2 or later.

error TypeError: Cannot destructure property 'app' of 'context' as it is undefined. ↓

cause Using named export `{ viteSSR }` from plugin.js instead of default export.

fix

Change import to import viteSSR from 'vite-ssr/plugin.js' (default export).

error Error: [vite-ssr] The 'url' property is missing or invalid. ↓

cause Accessing `url` properties assuming Location type after v0.15.0 breaking change.

fix

Update code to use URL API: e.g., url.searchParams.get('q') instead of url.search.

error Warning: React version mismatch. Expected 17, got 18. ↓

cause vite-ssr peer dependency requires React 17; React 18 is not officially supported.

fix

Downgrade React to 17 or use a compatible fork; check for updates on v0.18.0.

Warnings

breaking In v0.15.0 the `url` object in SSR context changed from `Location` type to `URL` type. ↓

fix Update code that accesses `url` properties (e.g., `url.search` vs `url.searchParams`).

breaking v0.17.0 dropped support for Vite 3; requires Vite 4+. ↓

fix Upgrade Vite to version 4, and migrate Vite config as per Vite migration guide.

deprecated react-router-dom v5 support is deprecated; migrate to v6. ↓

fix Update package.json: replace 'react-router-config' and 'react-router-dom@5' with 'react-router-dom@6'. Adjust route config shape.

gotcha The plugin must be imported as `import viteSSR from 'vite-ssr/plugin.js'` (default export). Using named import causes runtime error. ↓

fix Use default import syntax.

gotcha State serialization may fail if data contains already escaped characters (e.g., newlines). Fixed in v0.14.2. ↓

fix Upgrade to v0.14.2+ or manually sanitize state values.

breaking In v0.14.0 state serialization changed to JSON, breaking custom serialization logic. ↓

fix Remove custom serializer functions; data is now JSON-serialized automatically.

Install

npm install vite-ssr

yarn add vite-ssr

pnpm add vite-ssr

Imports

viteSSR (default)
wrong
```
const viteSSR = require('vite-ssr')
```
correct
```
import viteSSR from 'vite-ssr'
```
ESM-only; CJS require will fail. Use 'vite-ssr/vue' or 'vite-ssr/react' for better type inference.
viteSSR plugin
wrong
```
import { viteSSR } from 'vite-ssr/plugin.js'
```
correct
```
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
wrong
```
import { viteSSR } from 'vite-ssr/vue'
```
correct
```
import viteSSR from 'vite-ssr/vue'
```
Framework-specific entry points are default exports for better type inference.

viteSSR type

wrong

import { ViteSSRContext } from 'vite-ssr'

correct

import type { ViteSSRContext } from 'vite-ssr'

Type-only import to avoid runtime side effects.

Quickstart

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 || {}
  // }
})