Vite SSG

Server-side generation for Vite.

ℹ️ Vite 2 is supported from v0.2.x, Vite 1's support is discontinued.

Install

This library requires Node.js version >= 14

npm i -D vite-ssg @vue/server-renderer @vue/compiler-sfc [email protected] @vueuse/head

// package.json
{
  "scripts": {
    "dev": "vite",
-   "build": "vite build"
+   "build": "vite-ssg build"
  }
}

// src/main.ts
import { ViteSSG } from 'vite-ssg'
import App from './App.vue'

// `export const createApp` is required
export const createApp = ViteSSG(
  // the root component
  App,
  // vue-router options
  { routes },
  // function to have custom setups
  ({ app, router, isClient }) => {
    // install plugins etc.
  }
)

Single Page SSG

To have SSG for the index page only (without vue-router), import from vite-ssg/single-page instead.

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

export const createApp = ViteSSG(App)

<ClientOnly/>

Component ClientOnly is registered globally along with the app creation.

<client-only>
  <your-client-side-components />
</client-only>

Document head

From v0.4.0, we ships @vueuse/head to manage the document head out-of-box. You can directly use it in your pages/components, for example:

<template>
  <button @click="count++">Click</button>
</template>

<script setup>
import { useHead } from '@vueuse/head'

useHead({
  title: 'Website Title',
  meta: [
    {
      name: `description`,
      content: `Website description`,
    },
  ],
})
</script>

That's all, no configuration needed. Vite SSG will handle the server-side rendering and merging automatically.

Refer to @vueuse/head's docs for more usage about useHead.

Configuration

You can pass options to Vite SSG in the ssgOptions field of your vite.config.js

// vite.config.js

export default {
  plugins: [ /*...*/ ],
  ssgOptions: {
    script: 'async'
  }
}

See [src/types.ts] for more options avaliable.

Custom Routes to Render

You can use the includedRoutes hook to exclude/include route paths to render, or even provide some complete custom ones.

// vite.config.js

export default {
  plugins: [ /*...*/ ],
  ssgOptions: {
    includedRoutes(routes) {
      // exclude all the route paths that contains 'foo'
      return paths.filter(i => !i.includes('foo'))
    }
  }
}

Comparsion

Use Vitepress when you want:

• Zero config, out-of-box
• Single-purpose documentation site
• Lightweight (No double payload)

Use Vite SSG when you want:

• More controls on the build process and tooling
• The flexible plugin systems
• Multi-purpose application with some SSG to improve SEO and loading speed

Cons:

• Double payload

Example

See Vitesse

Thanks to the prior work

• vitepress
• vue3-vite-ssr-example
• vite-ssr

License

MIT License © 2020 Anthony Fu