npm package: @mcn-info/vite-ssr
Description: Vite utility for server side rendering
Author: Fran Dios
Latest version: 2.0.3

<p align="center">
  <img width="180" src="./logo.svg" alt="Vite SSR logo">
</p>

<h1 align="center">@mcn-info/vite-ssr</h1>

<p align="center">
  Simple yet powerful Server Side Rendering for Vite 8 in Node.js.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@mcn-info/vite-ssr"><img src="https://img.shields.io/npm/v/@mcn-info/vite-ssr.svg" alt="npm version"></a>
  <img src="https://img.shields.io/npm/l/@mcn-info/vite-ssr.svg" alt="license">
</p>

---

- **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)

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

```ts
// 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()],
})
```

```ts
// 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.
})
```

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

## Quick Start (React)

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

```ts
// 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()],
})
```

```tsx
// 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](./docs/configuration.md#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](./docs/getting-started.md) | Full setup from zero to working SSR |
| [Configuration](./docs/configuration.md) | Plugin options, handler options, CLI, build-time globals |
| [Data Fetching](./docs/data-fetching.md) | initialState, route guards, Suspense, serverPrefetch |
| [Head Management](./docs/head-management.md) | Unhead (Vue), react-helmet-async (React) |
| [Production](./docs/production.md) | Build output, Express server, render API, deployment |
| [API Reference](./docs/api-reference.md) | Exhaustive type-level reference by import path |
| [TypeScript](./docs/typescript.md) | Import paths, type augmentation, typed state |
| [Recipes](./docs/recipes.md) | Pinia, Apollo, CSS-in-JS, i18n, error pages, middleware |

## Examples

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

## Contributing

See the [contributing guide](./docs/contributing.md) for setup instructions and PR guidelines.

## Credits

This project is a fork of [vite-ssr](https://github.com/frandiox/vite-ssr) by [Fran Dios](https://github.com/frandiox), later maintained by [flow-tools](https://github.com/flow-tools/vite-ssr). Migrated to ESM, Vite 8, Unhead, and pnpm.

## License

[MIT](./LICENSE)