vite-react-ssg

0.9.1-beta.1 verified Mon Apr 27 auth: no javascript

Static-site generation for React on Vite, supporting React Router v6 with data routes, lazy loading, and dynamic routes via getStaticPaths. Current stable version is v0.9.0, with frequent beta releases, actively maintained. Provides SSR dev server, CSR fallback, ClientOnly component, CSS-in-JS support (styled-components), and critical CSS extraction via beasties/critters. Key differentiator: lightweight alternative to Next.js SSG/ISR for Vite + React projects, with ESM-only, TypeScript types included.

Common errors

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

cause Missing type definitions because the package doesn't ship with types? Actually it does, but the import path may be wrong.

fix

Ensure you are using ESM import and that tsconfig.json includes 'moduleResolution': 'bundler' or 'node16'.

error Error: ViteReactSSG is not a function ↓

cause Trying to use require() on an ESM-only package.

fix

Change to ESM import: import { ViteReactSSG } from 'vite-react-ssg'

error TypeError: (0 , vite_react_ssg__WEBPACK_IMPORTED_MODULE_0__.ViteReactSSG) is not a function ↓

cause Webpack bundling issue; vite-react-ssg is designed for Vite only.

fix

Do not use vite-react-ssg with Webpack; it must be used with Vite.

error Error: RouteRecord is not a constructor ↓

cause Importing RouteRecord as a value instead of type.

fix

Use import type { RouteRecord } from 'vite-react-ssg' to avoid runtime inclusion.

Warnings

breaking React Router v7 now has built-in SSG support. vite-react-ssg is recommended only for v6 users. ↓

fix If using React Router v7, migrate to its official SSG. For v6, continue using vite-react-ssg.

gotcha hydrateRoot is not a function in React 19, fixed in v0.8.7. ↓

fix Upgrade to v0.8.7 or later to avoid hydration errors with React 19.

deprecated critters is deprecated in favor of beasties for critical CSS extraction. ↓

fix Install 'beasties' instead of 'critters' for better critical CSS support.

gotcha Using CommonJS require() to import vite-react-ssg will fail because it's ESM-only. ↓

fix Use ESM import syntax (import { ... } from 'vite-react-ssg').

Install

npm install vite-react-ssg

yarn add vite-react-ssg

pnpm add vite-react-ssg

Imports

ViteReactSSG

wrong

const ViteReactSSG = require('vite-react-ssg')

correct

import { ViteReactSSG } from 'vite-react-ssg'

ESM-only; CommonJS require() will fail.

RouteRecord
wrong
```
import { RouteRecord } from 'vite-react-ssg'
```
correct
```
import type { RouteRecord } from 'vite-react-ssg'
```
RouteRecord is a TypeScript type, import with `import type` to avoid runtime error.

ViteReactSSG (single-page)

wrong

import { ViteReactSSG } from 'vite-react-ssg/single-page' (same, but often confused with main import)

correct

import { ViteReactSSG } from 'vite-react-ssg/single-page'

For single-page SSG without react-router-dom, import from 'vite-react-ssg/single-page'.

Quickstart

Minimal setup: define routes, export createRoot, run build. ViteReactSSG generates static HTML per route.

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

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

// src/App.tsx
import React from 'react'
import type { RouteRecord } from 'vite-react-ssg'

const routes: RouteRecord[] = [
  {
    path: '/',
    element: <div>Hello SSG</div>,
  },
]

export default routes

// src/main.tsx
import { ViteReactSSG } from 'vite-react-ssg'
import routes from './App'

export const createRoot = ViteReactSSG({ routes })

// package.json scripts
{
  "scripts": {
    "build": "vite-react-ssg build",
    "dev": "vite-react-ssg dev"
  }
}