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–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ViteSSG
✓ import { ViteSSG } from 'vite-ssg'
✗ const { ViteSSG } = require('vite-ssg')
The `vite-ssg` package is ESM-only since v27.0.0, so CommonJS `require()` is not supported.
ViteSSG (Single Page)
✓ import { ViteSSG } from 'vite-ssg/single-page'
✗ import { ViteSSG } from 'vite-ssg'
Use this specific import path for static-site generation of an index page only, without `vue-router`.
useHead
✓ import { useHead } from '@unhead/vue'
✗ import { useHead } from 'vite-ssg'
`@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`.
ClientOnly
✓ import { ClientOnly } from 'vite-ssg/client'
✗ import { ClientOnly } from 'vite-ssg'
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.
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.
import { ViteSSG } from 'vite-ssg'
import App from './App.vue'
import { createRouter, createWebHistory } from 'vue-router'
const routes = [
{ path: '/', component: () => import('./pages/Home.vue') },
{ path: '/about', component: () => import('./pages/About.vue') },
]
export const createApp = ViteSSG(
App,
{ routes, base: import.meta.env.BASE_URL },
({ app, router, routes, isClient, initialState }) => {
// install plugins, register global components, etc.
// app.use(somePlugin)
// if (isClient) console.log('Client-side setup finished!')
}
)
// package.json script update
// {
// "scripts": {
// "dev": "vite",
// "build": "vite-ssg build"
// }
// }
Debug
Known issues
breakingVite SSG v28.0.0 and newer require Node.js v20 or greater. Projects on older Node.js versions must upgrade their environment.fixUpgrade your Node.js environment to version 20.x or higher (e.g., using `nvm install 20` and `nvm use 20`).
affects: >=28.0.0
breakingVite 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.fixEnsure 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.
affects: >=27.0.0
gotchaThe 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.fixChange `createApp(App).mount('#app')` to `export const createApp = ViteSSG(App, routerOptions, setupFn)` in your application entry file. affects: >=0.2.x
gotchaTo 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 */ }`.fixUtilize `import.meta.env.SSR` conditional blocks to separate server-side and client-side code paths for optimal bundle size.
affects: >=0.2.x
breakingVite 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.fixConsult 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.
affects: >=28.3.0 (and previous major/minor bumps)
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module ...vite-ssg... not supported.
Attempting to import `vite-ssg` using CommonJS `require()` syntax in a Node.js environment or a configuration that expects CJS.
fixMigrate 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.
Error: vite-ssg requires Node.js version >= 20.0.0
The installed version of `vite-ssg` (v28.0.0+) requires a Node.js runtime of version 20 or higher.
fixUpgrade 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.
TypeError: createApp is not a function (runtime error during SSG build)
The `createApp` function required by Vite SSG is not exported correctly from your application's entry file, or the `ViteSSG` wrapper was not used.
fixVerify that your `src/main.ts` (or equivalent) contains `export const createApp = ViteSSG(...)` as demonstrated in the documentation, rather than directly `createApp(...).mount(...)`.
Audit
Dependencies
beastiesrequiredFor automatic critical CSS generation, which is inlined in the HTML.
prettierrequiredPeer dependency, likely for code formatting or internal development consistency.
viterequiredCore build tool for the application, tightly integrated with Vite SSG.
vuerequiredCore UI framework for the application.
vue-routerrequiredFor client-side routing and enabling multi-page SSG.