vite-plugin-ssr-ssg

1.4.1 verified Mon Apr 27 auth: no javascript maintenance

Vite plugin for SSR and SSG across multiple frameworks (React, Preact, Vue). Current stable version is 1.4.1 (March 2021). Release cadence is irregular with minor feature releases and bug fixes. Key differentiators: declarative entry point, automatic page generation, preview in both SSR and CSR, convenient init script. Compared to vite-ssr and vite-ssg, it aims for cross-framework support and simpler CLI commands. Last release was over a year ago, so it's in maintenance mode.

Common errors

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

cause Package is not installed or Node cannot resolve ESM package.

fix

Install the package: npm install vite-plugin-ssr-ssg. Ensure Node >=12 and your project uses ESM ("type": "module" in package.json).

error TypeError: vitePluginSsrSsg is not a function ↓

cause Incorrect import (default vs named) or CJS require used instead of ESM import.

fix

Use import vitePluginSsrSsg from 'vite-plugin-ssr-ssg' (default import).

error Error: The plugin 'vite-plugin-ssr-ssg' doesn't support the current Vite version ↓

cause Vite version is incompatible (<2.0).

fix

Upgrade Vite to >=2.0.0.

Warnings

gotcha Plugin uses ESM-only distribution; requires Vite with ESM and Node >=12. CJS imports break. ↓

fix Use `import` syntax in all files. Set `"type": "module"` in package.json or use `.mjs` extension.

deprecated In v1.3.0, the `init` script changed to use `vite-ssrg init` but older versions used `vite-ssrg-init`. ↓

fix Run `yarn vite-ssrg init` or `npx vite-ssrg init`.

breaking v1.4.0 changed rollup config output format; plugins expecting CJS may fail. ↓

fix Update any custom rollup configuration in vite.config.ts to use ESM format.

gotcha Preact import path changed in v1.4.0 from 'preact' to 'preact/compat' to match SSR expectations. ↓

fix If using Preact, update imports to `import { h } from 'preact/compat'` or configure plugin with preactCompat option.

deprecated The `routes` option in plugin config was deprecated in v1.3.0 in favor of automatic route detection. Manual routes still work but will be removed in v2. ↓

fix Remove `routes` from plugin options and rely on automatic detection.

Install

npm install vite-plugin-ssr-ssg

yarn add vite-plugin-ssr-ssg

pnpm add vite-plugin-ssr-ssg

Imports

default

wrong

const vitePluginSsrSsg = require('vite-plugin-ssr-ssg')

correct

import vitePluginSsrSsg from 'vite-plugin-ssr-ssg'

ESM-only package; require() will fail. Use TypeScript with ESM.

defineConfig
wrong
```
import { defineConfig } from 'vite'
```
correct
```
import { defineConfig } from 'vite-plugin-ssr-ssg'
```
defineConfig is a re-exported helper from vite; using vite's directly works but plugin's version provides SSG defaults in v1.2+

VitePluginSsrSsgOptions

wrong

import { VitePluginSsrSsgOptions } from 'vite-plugin-ssr-ssg'

correct

import type { VitePluginSsrSsgOptions } from 'vite-plugin-ssr-ssg'

Options interface is a type-only import in v1.4+. Use `import type` for TS

Quickstart

Configuration example with React: sets up Vite with the plugin and defines static routes for SSG.

// vite.config.ts
import { defineConfig, VitePluginSsrSsgOptions } from 'vite-plugin-ssr-ssg';
import react from '@vitejs/plugin-react';

const ssgOptions: VitePluginSsrSsgOptions = {
  // optional: custom routes for SSG
  routes: ['/', '/about'],
};

export default defineConfig({
  plugins: [
    react(),
    vitePluginSsrSsg(ssgOptions),
  ],
});