• Vue 3 + React 18 — auto-detects your framework from Vite plugins
• Single entry file — one main.ts for both server and client, no boilerplate
• Vite 8 native — lightning-fast HMR even in SSR mode
• Lightweight — thin layer over Vite, unopinionated about routing and API logic
• TypeScript first — full type definitions for every export

Quick Start (Vue)

pnpm create vite my-app --template vue-ts
cd my-app
pnpm add @mcn-info/vite-ssr vue-router @unhead/vue

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import viteSSR from '@mcn-info/vite-ssr/plugin'

export default defineConfig({
  plugins: [viteSSR(), vue()],
})

// src/main.ts
import App from './App.vue'
import routes from './routes'
import viteSSR from '@mcn-info/vite-ssr/vue'

export default viteSSR(App, { routes }, ({ app, router, initialState }) => {
  // Initialize plugins, state management, etc.
})

npx vite-ssr dev   # SSR dev server with HMR
npx vite-ssr build # Production build (client + server)

Quick Start (React)

pnpm create vite my-app --template react-ts
cd my-app
pnpm add @mcn-info/vite-ssr react-router-dom react-ssr-prepass

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import viteSSR from '@mcn-info/vite-ssr/plugin'

export default defineConfig({
  plugins: [viteSSR(), react()],
})

// src/main.tsx
import App from './App'
import { routes } from './routes'
import viteSSR from '@mcn-info/vite-ssr/react'

export default viteSSR(App, { routes }, ({ initialState }) => {
  // Initialize state, etc.
})

Vite 8 note: Do not set ssr.noExternal: true in your Vite config. Vite 8's Module Runner evaluates inlined modules as ESM, which crashes on CJS packages like vue. See SSR Externalization for details.

How It Works

The plugin intercepts imports of @mcn-info/vite-ssr and redirects them to framework-specific entry points via virtual modules. It detects whether code is running on the server or client and provides the right environment automatically — so you write one entry file and the plugin handles the rest.

Documentation

| Guide | Description | |-------|-------------| | Getting Started | Full setup from zero to working SSR | | Configuration | Plugin options, handler options, CLI, build-time globals | | Data Fetching | initialState, route guards, Suspense, serverPrefetch | | Head Management | Unhead (Vue), react-helmet-async (React) | | Production | Build output, Express server, render API, deployment | | API Reference | Exhaustive type-level reference by import path | | TypeScript | Import paths, type augmentation, typed state | | Recipes | Pinia, Apollo, CSS-in-JS, i18n, error pages, middleware |

Examples

| Example | Description | |---------|-------------| | Vue | Vue 3 SSR with Unhead and API integration | | React | React 18 SSR with react-router-dom | | React + Apollo | React SSR with Apollo GraphQL | | Vanilla | Vanilla JS SSR (no framework) | | Node Server | Express production server for all examples |

Contributing

See the contributing guide for setup instructions and PR guidelines.

Credits

This project is a fork of vite-ssr by Fran Dios, later maintained by flow-tools. Migrated to ESM, Vite 8, Unhead, and pnpm.

License

MIT