{"id":22856,"library":"vite-plugin-ssg","title":"Vite Plugin SSG","description":"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.","status":"active","version":"0.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/The-CodeCave/vite-plugin-ssg","tags":["javascript","vite","vite-plugin","ssg","static-site-generation","react","islands","partial-hydration","typescript"],"install":[{"cmd":"npm install vite-plugin-ssg","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-ssg","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-ssg","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Tailwind CSS support in version 4","package":"@tailwindcss/vite","optional":true},{"reason":"Required for React Fast Refresh and JSX transform","package":"@vitejs/plugin-react","optional":false},{"reason":"Peer dependency for React versions 18 or 19","package":"react","optional":false},{"reason":"Peer dependency for React DOM","package":"react-dom","optional":false},{"reason":"Peer dependency for Vite version 5 or higher","package":"vite","optional":false}],"imports":[{"note":"The plugin is exported as a named export, not default. Use destructured import.","wrong":"import ssgPlugin from 'vite-plugin-ssg'","symbol":"ssgPlugin","correct":"import { ssgPlugin } from 'vite-plugin-ssg'"},{"note":"The interactive island component is exported as `Island`.","wrong":"import { IslandComponent } from 'vite-plugin-ssg'","symbol":"Island","correct":"import { Island } from 'vite-plugin-ssg'"},{"note":"SsgOptions is a TypeScript type, not a runtime value. Import it using `import type` to avoid runtime inclusion.","wrong":"import { SsgOptions } from 'vite-plugin-ssg'","symbol":"SsgOptions","correct":"import type { SsgOptions } from 'vite-plugin-ssg'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\nimport { ssgPlugin } from 'vite-plugin-ssg';\n\nexport default defineConfig({\n  plugins: [\n    react(),\n    ssgPlugin({\n      pages: ['src/pages/HomePage.tsx'],\n      config: {\n        outDir: 'dist/static',\n        baseUrl: '/static',\n        images: { enabled: true, formats: ['webp'], quality: 80 },\n        css: { minify: 'lightningcss' },\n        js: { minify: 'terser' },\n      },\n      verbose: false,\n    }),\n  ],\n});\n\n// src/pages/HomePage.tsx\nimport type { SsgOptions } from 'vite-plugin-ssg';\nimport { Island } from 'vite-plugin-ssg';\n\nexport const ssgOptions: SsgOptions = {\n  slug: 'home',\n  routeUrl: '/',\n  Head: () => (\n    <>\n      <title>My Home Page</title>\n      <meta name=\"description\" content=\"Welcome\" />\n    </>\n  ),\n};\n\nexport default function HomePage() {\n  return (\n    <div>\n      <h1>Welcome</h1>\n      <Island component=\"components/Counter\" props={{ count: 0 }} />\n    </div>\n  );\n}\n\n// src/components/Counter.tsx\n'use island';\n\nimport { useState } from 'react';\n\nexport default function Counter({ count }: { count: number }) {\n  const [value, setValue] = useState(count);\n  return <button onClick={() => setValue(v => v + 1)}>{value}</button>;\n}\n\n// Build command\n// npm run build","lang":"typescript","description":"Minimal setup for Vite SSG with React: configure plugin, create a page with SSR options, and define an island component for partial hydration."},"warnings":[{"fix":"Add `\"vite-plugin-ssg\": \"0.1.0\"` to dependencies with exact version pinning.","message":"Version 0.1.0 is an initial release; API may change without notice. Do not use in production without pinning exact version.","severity":"breaking","affected_versions":"0.1.0"},{"fix":"Add `'use island';` as the first line in island component files.","message":"Island components must have `'use island'` directive at the top of the file. Missing this directive will cause hydration errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure props are plain objects, strings, numbers, booleans, or arrays thereof.","message":"Island props must be JSON-serializable. Passing functions, Date objects, or React elements will cause runtime errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Set `slug` to a unique string for each page.","message":"The `slug` option in SsgOptions is currently required but may become optional in future versions. For now, always provide a slug.","severity":"deprecated","affected_versions":"0.1.0"},{"fix":"Use `component='components/Widget'` instead of `component='./src/components/Widget'`.","message":"The `component` prop in Island must be a path relative to the srcDir (default: 'src'). Do not include leading './' or '../'.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your project uses Vite 5.x and React 18+.","message":"The plugin requires Vite 5+ and React 18+. Older versions are not supported.","severity":"breaking","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Add `'use island';` as the very first line of the island component file.","cause":"Island component file missing the `'use island'` directive or it is not the first line.","error":"Error: 'use island' directive must be at the top of the file"},{"fix":"Use `import { ssgPlugin } from 'vite-plugin-ssg';` (named import).","cause":"Importing the plugin incorrectly (e.g., default import instead of named import).","error":"TypeError: ssgPlugin is not a function"},{"fix":"Provide `pages` array with paths to page files or folders.","cause":"The `ssgPlugin` was called without the `pages` option.","error":"Error: Missing required option 'pages'"},{"fix":"Ensure the path is relative to the configured `srcDir` (default 'src').","cause":"The `component` prop in Island points to a non-existent file or incorrect path.","error":"Error: Component '...' not found in src directory"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}