{"id":22692,"library":"vite-plugin-html-pages","title":"vite-plugin-html-pages","description":"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.","status":"active","version":"1.6.8","language":"javascript","source_language":"en","source_url":"https://github.com/paul-browne/vite-plugin-html-pages","tags":["javascript","vite","vite-plugin","vite-plugin-pages","vite-ssg","static-site-generator","ssg","file-based-routing","html-generator","typescript"],"install":[{"cmd":"npm install vite-plugin-html-pages","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-html-pages","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-html-pages","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime dependency for converting JavaScript functions to HTML strings. Must be installed alongside the plugin.","package":"javascript-to-html","optional":false},{"reason":"Peer dependency; plugin only works with Vite build tool (version >=5 required).","package":"vite","optional":false},{"reason":"Peer dependency (>=18) required by the plugin's internal SSR and rendering capabilities.","package":"react","optional":true},{"reason":"Peer dependency (>=18) required alongside React for server-side rendering.","package":"react-dom","optional":true}],"imports":[{"note":"Default export only. Using named import will result in 'undefined' in Vite config.","wrong":"import { htmlPages } from 'vite-plugin-html-pages'","symbol":"htmlPages","correct":"import htmlPages from 'vite-plugin-html-pages'"},{"note":"defineConfig is from Vite core, not from this plugin.","wrong":"import { defineConfig } from 'vite-plugin-html-pages'","symbol":"defineConfig","correct":"import { defineConfig } from 'vite'"},{"note":"All HTML tag helpers come from the separate 'javascript-to-html' package, not from this plugin.","wrong":"import { fragment } from 'vite-plugin-html-pages'","symbol":"fragment, html, body, h1, etc.","correct":"import { fragment, html, body, h1 } from 'javascript-to-html'"},{"note":"generateStaticParams must be a synchronous function, not async. If async needed, wrap in a sync function that returns a promise.","wrong":"export const generateStaticParams = async () => { ... }","symbol":"generateStaticParams","correct":"export function generateStaticParams() { ... }"}],"quickstart":{"code":"// vite.config.js\nimport { defineConfig } from 'vite'\nimport htmlPages from 'vite-plugin-html-pages'\n\nexport default defineConfig({\n plugins: [htmlPages()]\n})\n\n// src/index.ht.js\nimport { fragment, html, body, head, title, h1 } from 'javascript-to-html'\n\nexport default () => fragment(\n '',\n html({lang: 'en'},\n head(\n title('My website')\n ),\n body(\n h1('Hello world')\n )\n )\n)","lang":"javascript","description":"Creates a Vite project that generates a static index.html from a JavaScript function using vite-plugin-html-pages and javascript-to-html."},"warnings":[{"fix":"Rename all .page.js files to .ht.js and update imports/configuration accordingly.","message":"Route file extension changed from .page.js to .ht.js in v1.0.0.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Remove async keyword from generateStaticParams. Use synchronous pattern; if async data loading is needed, pre-fetch outside the function.","message":"generateStaticParams must be synchronous starting from v1.2.0. Async functions cause build errors.","severity":"breaking","affected_versions":">=1.2.0"},{"fix":"Use alternative route grouping methods if available, or prepare for removal by restructuring routes.","message":"The legacy route grouping syntax ( ) [parentheses] in filenames (e.g., (admin)/users.ht.js) is deprecated and may be removed in future versions.","severity":"deprecated","affected_versions":">=1.4.0"},{"fix":"Install the peer dependency: npm install javascript-to-html","message":"Plugin requires both 'javascript-to-html' and Vite as dependencies. Missing javascript-to-html causes runtime errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Install React and ReactDOM: npm install react react-dom","message":"Dev server rendering relies on React and ReactDOM >=18. If React is not installed, dev server fails silently.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review route tree to avoid conflicts; static routes take precedence over catch-all.","message":"Catch-all routes ([...slug]) consume all path segments; ensure no overlapping static routes exist.","severity":"gotcha","affected_versions":">=0.5.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Add and export a generateStaticParams function in the file: export function generateStaticParams() { return [...] }","cause":"A dynamic route file is missing the generateStaticParams export, or it is not exported correctly.","error":"Error: [vite-plugin-html-pages] Missing export 'generateStaticParams' in ..."},{"fix":"Change import: import htmlPages from 'vite-plugin-html-pages' (remove curly braces).","cause":"Using named import instead of default import for htmlPages.","error":"TypeError: htmlPages is not a function"},{"fix":"Run: npm install javascript-to-html","cause":"The peer dependency 'javascript-to-html' is not installed.","error":"Error: Cannot find module 'javascript-to-html'"},{"fix":"Remove the async keyword: export function generateStaticParams() { ... } (synchronous).","cause":"generateStaticParams is declared as async, which is not supported since v1.2.0.","error":"Error: [vite-plugin-html-pages] generateStaticParams must be a synchronous function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}