How It Works

bini-ssg is a Vite build plugin that runs during vite build. It:

Static routes (/, /blog) come straight from the route list. Dynamic routes like the highlighted /blog/:slug are discovered by crawling.

• Reads your route list from bini-router's generateRouteManifest()
• Calls your render() function for every static route
• Crawls each rendered HTML for internal <a href> links and discovers dynamic routes (e.g. /blog/my-first-post linked from /blog)
• Pre-renders every discovered dynamic route with your render() - full HTML, not a shell
• Falls back to shell pages only for dynamic routes that were never linked (still valid - hydrated on client)
• Writes one index.html per route into your output directory

Your render() Function

The render() function is exported from src/main.tsx and called by bini-ssg for every static route:

import { createRoot } from 'react-dom/client'
import App from './App'

// Client mount
createRoot(document.getElementById('root')!).render(<App />)

// SSG render (called by bini-ssg, Node-only)
export async function render(url: string): Promise<string> {
  const { renderToString } = await import('react-dom/server')
  const { StaticRouter } = await import('react-router-dom/server')
  const { AppRoutes } = await import('./App')

  return renderToString(
    <StaticRouter location={url}>
      <AppRoutes />
    </StaticRouter>
  )
}

This function uses React 19's renderToPipeableStream under the hood with StaticRouter from React Router, producing real server-rendered HTML.

Build Command

npm run build type-checks (TypeScript projects) and then runs vite build. The bini-ssg plugin drives pre-rendering as part of that same build.

$ npm run build

Output Structure

Each route becomes its own folder with an index.html. Highlighted files were found by crawling and pre-rendered; the [slug] and [...slug] folders are shell fallbacks for dynamic routes that were never linked.

Crawling & Shell Fallback

After pre-rendering static routes, bini-ssg parses each HTML file for internal links and crawls them:

This repeats recursively - if /blog/my-first-post links to /users/123, that page is also pre-rendered. Crawling respects your base path and skips external links, hashes, and /api/*.

Only dynamic routes that were never discovered during crawling get a shell page with a marker script:

<script>window.__BINI_SHELL__=true;</script>

Your client entry checks this flag to decide between createRoot and hydrateRoot:

const root = document.getElementById('root')!

if (window.__BINI_SHELL__) {
  createRoot(root).render(<App />)
} else {
  hydrateRoot(root, <App />)
}

404 Handling

You can enable 404.html generation with the fallback option:

// vite.config.ts
import { defineConfig } from 'vite'
import { biniSSG } from 'bini-ssg'

export default defineConfig({
  plugins: [
    // ...other plugins
    biniSSG({
      fallback: true,  // Render '/404' as 404.html
    }),
  ],
})

Works on Any Fully Static Host

Complete Example

A full setup for deploying to GitHub Pages with true SSG:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { biniroute } from 'bini-router'
import { biniEnv } from 'bini-env'
import { biniSSG } from 'bini-ssg'

export default defineConfig({
  base: '/my-app/',  // GitHub Pages subpath
  plugins: [
    react(),
    biniEnv(),
    ...biniroute(),
    biniSSG({
      fallback: true,        // Generate 404.html
    }),
  ],
})

Run npm run build, then push the contents of dist/ to your GitHub Pages branch (or upload them through the GitHub Pages UI).

$ npm run build