{"id":12382,"library":"vite-ssg","title":"Vite SSG","description":"Vite SSG is a library designed for static-site generation (SSG) of Vue 3 applications built with Vite. It streamlines the process of pre-rendering your Vue application into static HTML files, enhancing SEO and initial load performance. The current stable version is v28.3.0, and the project maintains a regular release cadence, often aligning with updates to its peer dependencies like Vite and Vue Router, with occasional minor and patch releases. Key differentiators include its tight integration with the Vite ecosystem, built-in support for `@unhead/vue` for document head management, and automatic critical CSS generation via the `beasties` package. Since v27.0.0, Vite SSG has exclusively adopted an ESM-only module format, dropping CommonJS support entirely. It supports Vue Router for multi-page SSG and offers a specialized entry point for single-page SSG scenarios, requiring Node.js v20 or newer.","status":"active","version":"28.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/antfu-collective/vite-ssg","tags":["javascript","vite","vite-plugin","ssg","ssr","typescript"],"install":[{"cmd":"npm install vite-ssg","lang":"bash","label":"npm"},{"cmd":"yarn add vite-ssg","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-ssg","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"For automatic critical CSS generation, which is inlined in the HTML.","package":"beasties","optional":false},{"reason":"Peer dependency, likely for code formatting or internal development consistency.","package":"prettier","optional":false},{"reason":"Core build tool for the application, tightly integrated with Vite SSG.","package":"vite","optional":false},{"reason":"Core UI framework for the application.","package":"vue","optional":false},{"reason":"For client-side routing and enabling multi-page SSG.","package":"vue-router","optional":false}],"imports":[{"note":"The `vite-ssg` package is ESM-only since v27.0.0, so CommonJS `require()` is not supported.","wrong":"const { ViteSSG } = require('vite-ssg')","symbol":"ViteSSG","correct":"import { ViteSSG } from 'vite-ssg'"},{"note":"Use this specific import path for static-site generation of an index page only, without `vue-router`.","wrong":"import { ViteSSG } from 'vite-ssg'","symbol":"ViteSSG (Single Page)","correct":"import { ViteSSG } from 'vite-ssg/single-page'"},{"note":"`@unhead/vue` is integrated out-of-the-box for document head management, but it's a separate package and not re-exported directly from `vite-ssg`.","wrong":"import { useHead } from 'vite-ssg'","symbol":"useHead","correct":"import { useHead } from '@unhead/vue'"},{"note":"The `ClientOnly` component is globally registered, so direct import is often not needed, but if explicitly desired, it lives under `vite-ssg/client`. When used, its children must be a function returning an element to prevent client-side API usage on the server.","wrong":"import { ClientOnly } from 'vite-ssg'","symbol":"ClientOnly","correct":"import { ClientOnly } from 'vite-ssg/client'"}],"quickstart":{"code":"import { ViteSSG } from 'vite-ssg'\nimport App from './App.vue'\nimport { createRouter, createWebHistory } from 'vue-router'\n\nconst routes = [\n  { path: '/', component: () => import('./pages/Home.vue') },\n  { path: '/about', component: () => import('./pages/About.vue') },\n]\n\nexport const createApp = ViteSSG(\n  App,\n  { routes, base: import.meta.env.BASE_URL },\n  ({ app, router, routes, isClient, initialState }) => {\n    // install plugins, register global components, etc.\n    // app.use(somePlugin)\n    // if (isClient) console.log('Client-side setup finished!')\n  }\n)\n\n// package.json script update\n// {\n//   \"scripts\": {\n//     \"dev\": \"vite\",\n//     \"build\": \"vite-ssg build\"\n//   }\n// }\n","lang":"typescript","description":"This quickstart demonstrates the basic setup for a Vue 3 application using Vite SSG with Vue Router, defining a `createApp` export and configuring the build script."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20.x or higher (e.g., using `nvm install 20` and `nvm use 20`).","message":"Vite SSG v28.0.0 and newer require Node.js v20 or greater. Projects on older Node.js versions must upgrade their environment.","severity":"breaking","affected_versions":">=28.0.0"},{"fix":"Ensure your project is configured for ESM, using `type: \"module\"` in `package.json` and `import` statements instead of `require()`. Update `vite.config.js` to `vite.config.ts` or `vite.config.mjs` if needed.","message":"Vite SSG moved to ESM-only (ECMAScript Modules) from v27.0.0, dropping support for CommonJS (CJS) module format. This impacts how the library is imported and used in projects.","severity":"breaking","affected_versions":">=27.0.0"},{"fix":"Change `createApp(App).mount('#app')` to `export const createApp = ViteSSG(App, routerOptions, setupFn)` in your application entry file.","message":"The main entry file (e.g., `src/main.ts`) must `export const createApp` instead of directly mounting the app (`createApp(App).mount('#app')`). This is crucial for Vite SSG to properly hook into the application creation process.","severity":"gotcha","affected_versions":">=0.2.x"},{"fix":"Utilize `import.meta.env.SSR` conditional blocks to separate server-side and client-side code paths for optimal bundle size.","message":"To enable Rollup to effectively tree-shake client-side code and remove server-only logic during the client build, wrap server-specific code blocks with `if (import.meta.env.SSR) { /* server code */ } else { /* client code */ }`.","severity":"gotcha","affected_versions":">=0.2.x"},{"fix":"Consult the `vite-ssg` changelog and your `package.json` to ensure `vite`, `vue`, and `vue-router` versions satisfy the `vite-ssg` peer dependency requirements. Update them as necessary.","message":"Vite SSG frequently updates its peer dependency ranges for `vite` and `vue-router` (e.g., supporting Vite v8 and Vue Router v5 in v28.3.0). While this offers broader compatibility, ensure your project's versions of these dependencies meet the required ranges to avoid build or runtime issues.","severity":"breaking","affected_versions":">=28.3.0 (and previous major/minor bumps)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Migrate your project to use ECMAScript Modules (ESM). Add `\"type\": \"module\"` to your `package.json` and use `import` statements instead of `require()`. Ensure `vite.config.js` is named `vite.config.ts` or `vite.config.mjs` if it contains ESM syntax.","cause":"Attempting to import `vite-ssg` using CommonJS `require()` syntax in a Node.js environment or a configuration that expects CJS.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ...vite-ssg... not supported."},{"fix":"Upgrade your Node.js environment. Use a version manager like `nvm` (`nvm install 20 && nvm use 20`) or update your runtime environment to Node.js 20 or newer.","cause":"The installed version of `vite-ssg` (v28.0.0+) requires a Node.js runtime of version 20 or higher.","error":"Error: vite-ssg requires Node.js version >= 20.0.0"},{"fix":"Verify that your `src/main.ts` (or equivalent) contains `export const createApp = ViteSSG(...)` as demonstrated in the documentation, rather than directly `createApp(...).mount(...)`.","cause":"The `createApp` function required by Vite SSG is not exported correctly from your application's entry file, or the `ViteSSG` wrapper was not used.","error":"TypeError: createApp is not a function (runtime error during SSG build)"}],"ecosystem":"npm"}