Vite Plugin SSG

0.1.0 verified Mon Apr 27 auth: no javascript

A Vite plugin for static site generation with React and island architecture (partial hydration). Version 0.1.0. Currently in early development with frequent breaking changes. Key differentiators: island-based partial hydration, built-in image optimization (WebP/AVIF), per-page CSS extraction with Tailwind support, and Firebase hosting configuration automation. Ships TypeScript types.

Common errors

error Error: 'use island' directive must be at the top of the file ↓

cause Island component file missing the `'use island'` directive or it is not the first line.

fix

Add 'use island'; as the very first line of the island component file.

error TypeError: ssgPlugin is not a function ↓

cause Importing the plugin incorrectly (e.g., default import instead of named import).

fix

Use import { ssgPlugin } from 'vite-plugin-ssg'; (named import).

error Error: Missing required option 'pages' ↓

cause The `ssgPlugin` was called without the `pages` option.

fix

Provide pages array with paths to page files or folders.

error Error: Component '...' not found in src directory ↓

cause The `component` prop in Island points to a non-existent file or incorrect path.

fix

Ensure the path is relative to the configured srcDir (default 'src').

Warnings

breaking Version 0.1.0 is an initial release; API may change without notice. Do not use in production without pinning exact version. ↓

fix Add `"vite-plugin-ssg": "0.1.0"` to dependencies with exact version pinning.

gotcha Island components must have `'use island'` directive at the top of the file. Missing this directive will cause hydration errors. ↓

fix Add `'use island';` as the first line in island component files.

gotcha Island props must be JSON-serializable. Passing functions, Date objects, or React elements will cause runtime errors. ↓

fix Ensure props are plain objects, strings, numbers, booleans, or arrays thereof.

deprecated The `slug` option in SsgOptions is currently required but may become optional in future versions. For now, always provide a slug. ↓

fix Set `slug` to a unique string for each page.

gotcha The `component` prop in Island must be a path relative to the srcDir (default: 'src'). Do not include leading './' or '../'. ↓

fix Use `component='components/Widget'` instead of `component='./src/components/Widget'`.

breaking The plugin requires Vite 5+ and React 18+. Older versions are not supported. ↓

fix Ensure your project uses Vite 5.x and React 18+.

Install

npm install vite-plugin-ssg

yarn add vite-plugin-ssg

pnpm add vite-plugin-ssg

Imports

ssgPlugin
wrong
```
import ssgPlugin from 'vite-plugin-ssg'
```
correct
```
import { ssgPlugin } from 'vite-plugin-ssg'
```
The plugin is exported as a named export, not default. Use destructured import.

Island

wrong

import { IslandComponent } from 'vite-plugin-ssg'

correct

import { Island } from 'vite-plugin-ssg'

The interactive island component is exported as `Island`.

SsgOptions
wrong
```
import { SsgOptions } from 'vite-plugin-ssg'
```
correct
```
import type { SsgOptions } from 'vite-plugin-ssg'
```
SsgOptions is a TypeScript type, not a runtime value. Import it using `import type` to avoid runtime inclusion.

Quickstart

Minimal setup for Vite SSG with React: configure plugin, create a page with SSR options, and define an island component for partial hydration.

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

export default defineConfig({
  plugins: [
    react(),
    ssgPlugin({
      pages: ['src/pages/HomePage.tsx'],
      config: {
        outDir: 'dist/static',
        baseUrl: '/static',
        images: { enabled: true, formats: ['webp'], quality: 80 },
        css: { minify: 'lightningcss' },
        js: { minify: 'terser' },
      },
      verbose: false,
    }),
  ],
});

// src/pages/HomePage.tsx
import type { SsgOptions } from 'vite-plugin-ssg';
import { Island } from 'vite-plugin-ssg';

export const ssgOptions: SsgOptions = {
  slug: 'home',
  routeUrl: '/',
  Head: () => (
    <>
      <title>My Home Page</title>
      <meta name="description" content="Welcome" />
    </>
  ),
};

export default function HomePage() {
  return (
    <div>
      <h1>Welcome</h1>
      <Island component="components/Counter" props={{ count: 0 }} />
    </div>
  );
}

// src/components/Counter.tsx
'use island';

import { useState } from 'react';

export default function Counter({ count }: { count: number }) {
  const [value, setValue] = useState(count);
  return <button onClick={() => setValue(v => v + 1)}>{value}</button>;
}

// Build command
// npm run build