Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ssgPlugin
✓ import { ssgPlugin } from 'vite-plugin-ssg'
✗ import ssgPlugin from 'vite-plugin-ssg'
The plugin is exported as a named export, not default. Use destructured import.
Island
✓ import { Island } from 'vite-plugin-ssg'
✗ import { IslandComponent } from 'vite-plugin-ssg'
The interactive island component is exported as `Island`.
SsgOptions
✓ import type { SsgOptions } from 'vite-plugin-ssg'
✗ import { SsgOptions } from 'vite-plugin-ssg'
SsgOptions is a TypeScript type, not a runtime value. Import it using `import type` to avoid runtime inclusion.
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
Errors
Common errors & fixes
Error: 'use island' directive must be at the top of the file
Island component file missing the `'use island'` directive or it is not the first line.
fixAdd `'use island';` as the very first line of the island component file.
TypeError: ssgPlugin is not a function
Importing the plugin incorrectly (e.g., default import instead of named import).
fixUse `import { ssgPlugin } from 'vite-plugin-ssg';` (named import). Error: Missing required option 'pages'
The `ssgPlugin` was called without the `pages` option.
fixProvide `pages` array with paths to page files or folders.
Error: Component '...' not found in src directory
The `component` prop in Island points to a non-existent file or incorrect path.
fixEnsure the path is relative to the configured `srcDir` (default 'src').
Audit
Dependencies
@tailwindcss/viteoptionalRequired for Tailwind CSS support in version 4
@vitejs/plugin-reactrequiredRequired for React Fast Refresh and JSX transform
reactrequiredPeer dependency for React versions 18 or 19
react-domrequiredPeer dependency for React DOM
viterequiredPeer dependency for Vite version 5 or higher