vite-plugin-ssr

0.4.142 verified Mon Apr 27 auth: no javascript

A Vite plugin for server-side rendering (SSR) that follows the Unix philosophy of doing one thing well. Current stable version is 0.4.142. It provides a lightweight, framework-agnostic SSR solution for Vite, unlike full-featured meta-frameworks like Next.js or Nuxt. It supports file-based routing, data fetching, and hydration. The plugin is actively maintained with frequent releases. Key differentiators: it is a simple Vite plugin rather than a full framework, supports any frontend framework (React, Vue, Svelte, etc.), and integrates seamlessly with existing Vite setups. Requires Node >=16, Vite >=3.1.0, and react-streaming >=0.3.5 (for React).

Common errors

error Cannot find module 'vite-plugin-ssr/plugin' ↓

cause Import path is incorrect; the module is not at the root.

fix

Install latest version and use import { vitePluginSsr } from 'vite-plugin-ssr/plugin'

error TypeError: (0 , vitePluginSsr) is not a function ↓

cause Default import instead of named import from the plugin subpath.

fix

Use import { vitePluginSsr } from 'vite-plugin-ssr/plugin' (curly braces)

error Property 'pageContext' does not exist on type 'PageContext' ↓

cause Using an older type definition or incorrect import path for PageContext.

fix

Import PageContext from 'vite-plugin-ssr/types' and ensure version >=0.4.0

error The 'vite-plugin-ssr' plugin requires Vite 3.1 or newer. ↓

cause Vite version is too old.

fix

Upgrade Vite to >=3.1.0

Warnings

breaking In v0.4, the import path changed from 'vite-plugin-ssr' to subpaths like 'vite-plugin-ssr/plugin', 'vite-plugin-ssr/client', etc. ↓

fix Update imports: use import { vitePluginSsr } from 'vite-plugin-ssr/plugin' instead of 'vite-plugin-ssr'

breaking PageContext type import changed from 'vite-plugin-ssr' to 'vite-plugin-ssr/types' ↓

fix Import PageContext from 'vite-plugin-ssr/types' instead of 'vite-plugin-ssr'

deprecated The old `render` function signature (pageContext, renderPage) is deprecated; use the new context-based API. ↓

fix Use async function render(pageContext) with explicit return of { pageHtml } or similar

gotcha The plugin requires Vite >=3.1.0 and Node >=16. Using older versions will cause build failures. ↓

fix Update Vite to >=3.1.0 and Node to >=16

gotcha Client-side code that uses react-streaming must ensure the package is installed as a dependency (not just peer dep). ↓

fix Run npm install react-streaming

Install

npm install vite-plugin-ssr

yarn add vite-plugin-ssr

pnpm add vite-plugin-ssr

Imports

vitePluginSsr
wrong
```
import vitePluginSsr from 'vite-plugin-ssr'
```
correct
```
import { vitePluginSsr } from 'vite-plugin-ssr/plugin'
```
The main export is named, not default. Also, it's imported from 'vite-plugin-ssr/plugin' subpath, not the root.
PageContext
wrong
```
import { PageContext } from 'vite-plugin-ssr'
```
correct
```
import type { PageContext } from 'vite-plugin-ssr/types'
```
PageContext is a type and should be imported from the types subpath. Using value import will cause runtime errors.
usePageContext
wrong
```
import { usePageContext } from 'vite-plugin-ssr'
```
correct
```
import { usePageContext } from 'vite-plugin-ssr/client'
```
Client-side hooks like usePageContext are exported from the client subpath, not the root.

Quickstart

Basic SSR setup with React: plugin configuration, a page component, and a server-side render function.

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

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

// pages/index.page.tsx
import { usePageContext } from 'vite-plugin-ssr/client'

export default function Page() {
  const { urlParsed } = usePageContext()
  return <h1>Hello {urlParsed.pathname}</h1>
}

// renderer/_default.page.server.tsx
import { renderToString } from 'react-dom/server'
import { PageContext } from 'vite-plugin-ssr/types'
import { PageWrapper } from './PageWrapper'

export async function render(pageContext: PageContext) {
  const pageHtml = renderToString(
    <PageWrapper pageContext={pageContext} />
  )
  return { pageHtml }
}