vite-plugin-html-pages

1.6.8 verified Mon Apr 27 auth: no javascript

vite-plugin-html-pages (v1.6.8) is a minimal static site generation plugin for Vite that uses JavaScript functions returning HTML strings, built on the javascript-to-html library. It employs file-based routing akin to Next.js's pages router—supporting static, dynamic ([slug]), multiple parameters, catch-all, optional catch-all, index routes, and route groups. Unlike full-featured SSGs like Astro or Nuxt, this plugin provides a lightweight, framework-agnostic approach to generating static HTML without a component system or complex build pipeline. It automatically generates sitemap.xml, 404.html, RSS feeds, and includes dev server SSR rendering with fetch caching. Ships TypeScript types. Requires Vite >=5 and Node >=18. Release cadence: active maintenance with frequent updates.

Common errors

error Error: [vite-plugin-html-pages] Missing export 'generateStaticParams' in ... ↓

cause A dynamic route file is missing the generateStaticParams export, or it is not exported correctly.

fix

Add and export a generateStaticParams function in the file: export function generateStaticParams() { return [...] }

error TypeError: htmlPages is not a function ↓

cause Using named import instead of default import for htmlPages.

fix

Change import: import htmlPages from 'vite-plugin-html-pages' (remove curly braces).

error Error: Cannot find module 'javascript-to-html' ↓

cause The peer dependency 'javascript-to-html' is not installed.

fix

Run: npm install javascript-to-html

error Error: [vite-plugin-html-pages] generateStaticParams must be a synchronous function ↓

cause generateStaticParams is declared as async, which is not supported since v1.2.0.

fix

Remove the async keyword: export function generateStaticParams() { ... } (synchronous).

Warnings

breaking Route file extension changed from .page.js to .ht.js in v1.0.0. ↓

fix Rename all .page.js files to .ht.js and update imports/configuration accordingly.

breaking generateStaticParams must be synchronous starting from v1.2.0. Async functions cause build errors. ↓

fix Remove async keyword from generateStaticParams. Use synchronous pattern; if async data loading is needed, pre-fetch outside the function.

deprecated The legacy route grouping syntax ( ) [parentheses] in filenames (e.g., (admin)/users.ht.js) is deprecated and may be removed in future versions. ↓

fix Use alternative route grouping methods if available, or prepare for removal by restructuring routes.

gotcha Plugin requires both 'javascript-to-html' and Vite as dependencies. Missing javascript-to-html causes runtime errors. ↓

fix Install the peer dependency: npm install javascript-to-html

gotcha Dev server rendering relies on React and ReactDOM >=18. If React is not installed, dev server fails silently. ↓

fix Install React and ReactDOM: npm install react react-dom

gotcha Catch-all routes ([...slug]) consume all path segments; ensure no overlapping static routes exist. ↓

fix Review route tree to avoid conflicts; static routes take precedence over catch-all.

Install

npm install vite-plugin-html-pages

yarn add vite-plugin-html-pages

pnpm add vite-plugin-html-pages

Imports

htmlPages
wrong
```
import { htmlPages } from 'vite-plugin-html-pages'
```
correct
```
import htmlPages from 'vite-plugin-html-pages'
```
Default export only. Using named import will result in 'undefined' in Vite config.

defineConfig

wrong

import { defineConfig } from 'vite-plugin-html-pages'

correct

import { defineConfig } from 'vite'

defineConfig is from Vite core, not from this plugin.

fragment, html, body, h1, etc.
wrong
```
import { fragment } from 'vite-plugin-html-pages'
```
correct
```
import { fragment, html, body, h1 } from 'javascript-to-html'
```
All HTML tag helpers come from the separate 'javascript-to-html' package, not from this plugin.
generateStaticParams
wrong
```
export const generateStaticParams = async () => { ... }
```
correct
```
export function generateStaticParams() { ... }
```
generateStaticParams must be a synchronous function, not async. If async needed, wrap in a sync function that returns a promise.

Quickstart

Creates a Vite project that generates a static index.html from a JavaScript function using vite-plugin-html-pages and javascript-to-html.

// vite.config.js
import { defineConfig } from 'vite'
import htmlPages from 'vite-plugin-html-pages'

export default defineConfig({
  plugins: [htmlPages()]
})

// src/index.ht.js
import { fragment, html, body, head, title, h1 } from 'javascript-to-html'

export default () => fragment(
  '<!doctype html>',
  html({lang: 'en'},
    head(
      title('My website')
    ),
    body(
      h1('Hello world')
    )
  )
)