{"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,"search_vec":"'18':120 '404.html':100 '5':117 'activ':123 'agnost':82 'akin':42 'approach':83 'astro':72 'automat':97 'base':40,147 'build':94 'built':28 'cach':111 'cadenc':122 'catch':55,59 'catch-al':54,58 'complex':93 'compon':90 'dev':105 'dynam':50 'employ':37 'featur':69 'feed':102 'fetch':110 'file':39,146 'file-bas':38 'file-based-rout':145 'framework':81 'framework-agnost':80 'frequent':126 'full':68 'full-featur':67 'function':24 'generat':17,85,98,143,151 'group':65 'html':4,9,26,34,87,150 'html-gener':149 'includ':104 'index':61 'javascript':23,32,128 'javascript-to-html':31 'librari':35 'lightweight':79 'like':71 'mainten':124 'minim':14 'multipl':52 'next.js':44 'node':119 'nuxt':74 'option':57 'page':5,10,46,136 'paramet':53 'pipelin':95 'plugin':3,8,18,76,132,135 'provid':77 'releas':121 'render':108 'requir':115 'return':25 'rout':41,62,64,148 'router':47 'rss':101 'server':106 'ship':112 'site':16,142 'sitemap.xml':99 'slug':51 'ssg':139,144 'ssgs':70 'ssr':107 'static':15,49,86,141 'static-site-gener':140 'string':27 'support':48 'system':91 'type':114 'typescript':113,152 'unlik':66 'updat':127 'use':22 'v1.6.8':11 'vite':2,7,20,116,129,131,134,138 'vite-plugin':130 'vite-plugin-html-pag':1,6 'vite-plugin-pag':133 'vite-ssg':137 'without':88","created_at":"2026-04-27T17:06:30.821011+00:00","updated_at":"2026-04-27T17:06:30.821011+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/paul-browne/vite-plugin-html-pages","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/vite-plugin-html-pages","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-18","next_check":"2026-07-26","install_tag":null}}