vite-react-ssg weekly downloads statistics

Vite React SSG

Static-site generation for React on Vite.

See demo(also document): docs

[!IMPORTANT] React Router v7 Notice

React Router v7 now has built-in SSG support. If you are using React Router v7, we recommend using its official SSG capabilities for better official support and integration.

vite-react-ssg will continue to maintain SSG functionality for React Router v6 users.

🎈 Support for @tanstack/router and wouter is in progress!

Support for the @tanstack/router router is still experimental, and pathname.lazy.tsx routes are not yet supported. For usage examples, see: main/examples/tanstack/src/main.tsx

Table of contents

• Usage
• Use CSR during development
• Extra route options
  • entry
  • getStaticPaths
• Data fetch
• lazy
• <ClientOnly/>
• Document head
  • Reactive head
• Redirect
• Public Base Path
• Future config
• CSS in JS
• Critical CSS
• Configuration
  • Custom Routes to Render
• Roadmap
• Credits

Usage

<pre> <b>npm i -D vite-react-ssg</b> <em>react-router-dom</em> </pre>

// package.json
{
  "scripts": {
-   "build": "vite build"
+   "build": "vite-react-ssg build"
    // If you need ssr when dev
-   "dev": "vite",
+   "dev": "vite-react-ssg dev",

    // OR if you want to use another vite config file
+   "build": "vite-react-ssg build -c another-vite.config.ts"
  }
}

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

export const createRoot = ViteReactSSG(
  // react-router-dom data routes
  { routes },
  // function to have custom setups
  ({ router, routes, isClient, initialState }) => {
    // do something.
  },
)

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

export const routes: RouteRecord[] = [
  {
    path: '/',
    element: <Layout />,
    entry: 'src/Layout.tsx',
    children: [
      {
        path: 'a',
        lazy: () => import('./pages/a'),
      },
      {
        index: true,
        Component: React.lazy(() => import('./pages/index')),
      },
      {
        path: 'nest/:b',
        lazy: () => {
          const Component = await import('./pages/nest/[b]')
          return { Component }
        },
        // To determine which paths will be pre-rendered
        getStaticPaths: () => ['nest/b1', 'nest/b2'],
      },
    ],
  },
]

Use CSR during development

Vite React SSG provide SSR (Server-Side Rendering) during development to ensure consistency between development and production as much as possible.

But if you want to use CSR during development, just:

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

Single Page SSG

For SSG of an index page only (i.e. without react-router-dom); import vite-react-ssg/single-page instead.

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

export const createRoot = ViteReactSSG(<App />)

Extra route options

The RouteObject of vite-react-ssg is based on react-router, and vite-react-ssg receives some additional properties.

getStaticPaths

The getStaticPaths() function should return an array of path to determine which paths will be pre-rendered by vite-react-ssg.

This function is only valid for dynamic route.

const route = {
  path: 'nest/:b',
  lazy: () => import('./pages/nest/[b]'),
  entry: 'src/pages/nest/[b].tsx',
  // To determine which paths will be pre-rendered
  getStaticPaths: () => ['nest/b1', 'nest/b2'],
}

entry

You are not required to use this field. It is only necessary when "prehydration style loss" occurs. It should be the path from root to the target file.

eg: src/pages/page1.tsx

lazy

These options work well with the lazy field.

// src/pages/[page].tsx
export function Component() {
  return (
    <div>{/* your component */}</div>
  )
}

export function getStaticPaths() {
  return ['page1', 'page2']
}

// src/routes.ts
const routes = [
  {
    path: '/:page',
    lazy: () => import('./pages/[page]'),
  }
]

Note that during the build process, vite-react-ssg will automatically detect the files directly dynamically imported in the function you pass to the lazy field. This helps vite-react-ssg to get the route's style files or other static resources during the build, preventing flash of unstyled content.

If you still encounter FOUC (flash of unstyled content), please open an issue.

If your component isn't loading, make sure you have wrapped it or its parent in Suspense tags as described in the React documentation.

See example.

Data fetch…