Registry / web-framework / vite-plugin-html-pages

vite-plugin-html-pages

library1.6.8jsnpmunverified

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.

web-framework devops

npm install vite-plugin-html-pages

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-HTML-P

vite-plugin-html-pages

web-frameworkjavascriptv1.6.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

htmlPages

✓ import htmlPages from 'vite-plugin-html-pages'

✗ import { htmlPages } from 'vite-plugin-html-pages'

Default export only. Using named import will result in 'undefined' in Vite config.

defineConfig

✓ import { defineConfig } from 'vite'

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

defineConfig is from Vite core, not from this plugin.

fragment, html, body, h1, etc.

✓ import { fragment, html, body, h1 } from 'javascript-to-html'

✗ import { fragment } from 'vite-plugin-html-pages'

All HTML tag helpers come from the separate 'javascript-to-html' package, not from this plugin.

generateStaticParams

✓ export function generateStaticParams() { ... }

✗ export const generateStaticParams = async () => { ... }

generateStaticParams must be a synchronous function, not async. If async needed, wrap in a sync function that returns a promise.

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') ) ) )

Debug

Known issues

breakingRoute 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.

affects: <1.0.0

breakinggenerateStaticParams 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.

affects: >=1.2.0

deprecatedThe 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.

affects: >=1.4.0

gotchaPlugin 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

affects: >=0.1.0

gotchaDev 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

affects: >=1.0.0

gotchaCatch-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.

affects: >=0.5.0

Errors

Common errors & fixes

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

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 [...] }

TypeError: htmlPages is not a function

Using named import instead of default import for htmlPages.

fix

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

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

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

fix

Run: npm install javascript-to-html

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

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

fix

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

Upgrade

Version history

1.6.8latest on npm

Audit

Dependencies

javascript-to-htmlrequiredRuntime dependency for converting JavaScript functions to HTML strings. Must be installed alongside the plugin.

viterequiredPeer dependency; plugin only works with Vite build tool (version >=5 required).

reactoptionalPeer dependency (>=18) required by the plugin's internal SSR and rendering capabilities.

react-domoptionalPeer dependency (>=18) required alongside React for server-side rendering.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/paul-browne/vite-plugin-html-pages ↗

packagehttps://www.npmjs.com/package/vite-plugin-html-pages ↗