Vite SSG

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module ...vite-ssg... not supported.

  cause Attempting to import `vite-ssg` using CommonJS `require()` syntax in a Node.js environment or a configuration that expects CJS.
  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.

• Error: vite-ssg requires Node.js version >= 20.0.0

  cause The installed version of `vite-ssg` (v28.0.0+) requires a Node.js runtime of version 20 or higher.
  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.

• TypeError: createApp is not a function (runtime error during SSG build)

  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.
  fix Verify that your `src/main.ts` (or equivalent) contains `export const createApp = ViteSSG(...)` as demonstrated in the documentation, rather than directly `createApp(...).mount(...)`.

Warnings

• breaking Vite SSG v28.0.0 and newer require Node.js v20 or greater. Projects on older Node.js versions must upgrade their environment.
  Fix: Upgrade your Node.js environment to version 20.x or higher (e.g., using `nvm install 20` and `nvm use 20`).
• breaking 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.
  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.
• gotcha 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.
  Fix: Change `createApp(App).mount('#app')` to `export const createApp = ViteSSG(App, routerOptions, setupFn)` in your application entry file.
• gotcha 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 */ }`.
  Fix: Utilize `import.meta.env.SSR` conditional blocks to separate server-side and client-side code paths for optimal bundle size.
• breaking 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.
  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.

Install

• npm install vite-ssg npm
• yarn add vite-ssg yarn
• pnpm add vite-ssg pnpm

Imports

• ViteSSG
  wrong:

  const { ViteSSG } = require('vite-ssg')

  correct:

  import { ViteSSG } from 'vite-ssg'

  The `vite-ssg` package is ESM-only since v27.0.0, so CommonJS `require()` is not supported.
• ViteSSG (Single Page)
  wrong:

  import { ViteSSG } from 'vite-ssg'

  correct:

  import { ViteSSG } from 'vite-ssg/single-page'

  Use this specific import path for static-site generation of an index page only, without `vue-router`.
• useHead
  wrong:

  import { useHead } from 'vite-ssg'

  correct:

  import { useHead } from '@unhead/vue'

  `@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
  wrong:

  import { ClientOnly } from 'vite-ssg'

  correct:

  import { ClientOnly } from 'vite-ssg/client'

  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.

Quickstart

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"
//   }
// }