npm - vite-plugin-html-pages - Versions diffs - 2.0.7 → 2.0.9 - Mend

vite-plugin-html-pages 2.0.7 → 2.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -5,133 +5,98 @@
 [![license](https://img.shields.io/npm/l/vite-plugin-html-pages.svg)](LICENSE)
 [![vite](https://img.shields.io/badge/vite-plugin-646CFF?logo=vite&logoColor=white)](https://vitejs.dev)
-Minimal **static site generation for Vite** using JavaScript files that return HTML.
+**Static site generation for Vite — no framework, no components, no magic.**
-Generate static HTML pages from `*.ht.js` modules using Vite and
-[`javascript-to-html`](https://www.npmjs.com/package/javascript-to-html).
+Write JavaScript (or TypeScript, or JSX) functions that return HTML.
+Get a complete static site with file-based routing, dynamic pages, data
+loading, an asset pipeline, sitemap, RSS, and a live dev server.
 ⭐ If this project helps you, please consider starring it.
-# Built for the Vite ecosystem
-Works seamlessly with:
--   ⚡ **Vite**
--   📦 **Rollup / Rolldown**
--   🧩 **javascript-to-html**
-A minimal **static site generator for Vite** that keeps pages as simple
-JavaScript functions returning HTML.
 ---
-# TL;DR
+## TL;DR
-Write:
+Write a function that returns HTML:
 ```js
 // 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')
-    )
-  )
-)
+export default () => `
+  <html lang="en">
+    <head>
+      <title>My website</title>
+      <link rel="stylesheet" href="/styles.css">
+    </head>
+    <body>
+      <h1>Hello world</h1>
+    </body>
+  </html>
+`
 ```
-Run:
+Run:
-``` bash
+```bash
 vite build
 ```
 Get:
-```html
-<!-- dist/index.html -->
-<!doctype html>
-<html lang="en">
-  <head>
-    <title>My website</title>
-  </head>
-  <body>
-    <h1>Hello world</h1>
-  </body>
-</html>
+```
+dist/
+  index.html      ← rendered, with <!DOCTYPE html> added for you
+  styles.css      ← bundled + minified, because your page referenced it
+  404.html        ← generated automatically
 ```
----
-# Features
-- File-based routing
-- Dynamic routes `[slug]`
-- Multiple parameters `[year]/[slug]`
-- Catch-all routes `[...slug]`
-- Optional catch-all routes `[...slug]?`
-- Route groups `(admin)/users.ht.js`
-- Index routes `blog/[slug]/index.ht.js`
-- Static params generation
-- Fetch caching for data loading
-- Dev server SSR rendering
-- Parallel static generation
-- Automatic `404.html`
-- Automatic `sitemap.xml`
-- Optional RSS feed generation
-- Debug logging
+That's the whole mental model. Everything else is convenience on top.
 ---
-# Installation
+## Features
-```bash
-npm install vite-plugin-html-pages javascript-to-html
-```
+- **File-based routing** — `src/about.ht.js` → `/about`
+- **Dynamic routes** — `[slug]`, `[year]/[slug]`, catch-all `[...path]`, optional catch-all `[...path]?`
+- **Route groups** — `(admin)/users.ht.js` → `/users`
+- **Bring your own HTML** — template literals, [javascript-to-html](https://www.npmjs.com/package/javascript-to-html), or JSX/TSX
+- **Data loading** — `data()` runs at build time, with built-in fetch caching
+- **Typed pages** — per-route param types inferred from the filename
+- **Smart asset pipeline** — JS/TS/CSS referenced by your HTML is bundled and minified; server-only code never leaks into `dist`
+- **Asset validation** — broken `<script src>` / stylesheet links fail the build
+- **Real dev server** — pages render on request with Vite HMR-style full reload and readable error frames
+- **Parallel static generation** — renders large sites concurrently
+- **`404.html`, `sitemap.xml`, RSS** — generated for you
 ---
-# Why this exists
+## Why this exists
-Modern static site tools are powerful, but they often introduce:
--   frameworks
--   component systems
--   complex build pipelines
--   opinionated conventions
+Modern static site tools are powerful, but they bring frameworks,
+component systems, hydration strategies, and opinionated conventions.
 Sometimes you just want to:
--   write HTML
--   organize pages in folders
--   generate static files
-`vite-plugin-html-pages` exists for that use case.
+- write HTML
+- organize pages in folders
+- run `vite build`
-It gives you:
--   file‑based routing
--   dynamic pages
--   static generation
--   dev server rendering
-while keeping pages as **simple JavaScript functions that return HTML**.
+`vite-plugin-html-pages` exists for exactly that. Pages are plain
+functions that return a string of HTML. No runtime ships to the
+browser unless *you* add a script.
 ---
-# Quick Start
+## Installation
+```bash
+npm install -D vite-plugin-html-pages
+```
-### vite.config.js
+Requires **Node 18+** and **Vite 8+**.
 ```js
+// vite.config.js
 import { defineConfig } from "vite"
 import htmlPages from "vite-plugin-html-pages"
@@ -140,230 +105,205 @@ export default defineConfig({
 })
 ```
----
-# Example Project Structure
+```bash
+vite        # dev server with live rendering
+vite build  # static site in dist/
 ```
-src/
-  index.ht.js
-  about.ht.js
-  blog/
-    index.ht.js
-    [slug].ht.js
-    [year]/[slug].ht.js
+Add the generated helper types to your `.gitignore`:
-  docs/
-    [...slug]?.ht.js
-  (admin)/
-    users.ht.js
+```
+.vite-plugin-html-pages/
 ```
 ---
-# Routing
-Routes are generated directly from the filesystem.
-| Feature | File | URL |
-|-----|-----|-----|
-| static routes | `index.ht.js` | `/` |
-| dynamic routes |  `blog/[slug].ht.js` | `/blog/my-post` |
-| multiple params | `blog/[year]/[slug].ht.js` | `/blog/2026/my-post` |
-| catch-all | `docs/[...slug].ht.js` | `/docs/api/auth/login` |
-| optional catch-all | `docs/[...slug]?.ht.js` | `/docs` or `/docs/getting-started` |
-| index routes | `products/[product]/index.ht.js` | `/products/iphone-18` |
-| route groups | `(admin)/users.ht.js` | `/users` |
----
-# Dynamic Routes
+## Project structure
 ```
-src/blog/[slug].ht.js
-```
+src/
+  index.ht.js            → /
+  about.ht.js            → /about
+  styles.css             → bundled if referenced
+  main.js                → bundled if referenced
+  lib/
+    api.js               → build-time only (never emitted unless referenced)
-Matches:
+  blog/
+    index.ht.js          → /blog
+    [slug].ht.js         → /blog/:slug
-```
-/blog/hello-world
-/blog/my-first-post
-```
+  docs/
+    [...path]?.ht.js     → /docs, /docs/a, /docs/a/b, ...
-Example:
+  (admin)/
+    users.ht.js          → /users
-``` js
-import { fragment, html, body, h1 } from 'javascript-to-html'
+  404.ht.js              → dist/404.html
+```
-export function generateStaticParams() {
-  return [
-    { slug: 'hello-world' },
-    { slug: 'my-first-post' }
-  ]
-}
+Any file ending in a page extension is a page. Everything else in
+`src/` is treated as an asset (see [Assets](#assets--styling)).
-export default ({ params }) => fragment(
-  '<!doctype html>',
-  html(
-    body(
-      h1(params.slug)
-    )
-  )
-)
-```
+Default page extensions: `.ht.js`, `.html.js`, `.ht.ts`, `.html.ts`,
+`.ht.jsx`, `.html.jsx`, `.ht.tsx`, `.html.tsx`.
 ---
-# Multiple Parameters
+## Writing pages
-```
-src/blog/[year]/[slug].ht.js
-```
+A page module's **default export** can be any of the following.
-Matches:
+### 1. A function returning an HTML string
-```
-/blog/2026/vite-routing
-/blog/2025/my-first-post
+```js
+export default ({ params, data, dev }) => `
+  <html>
+    <body><h1>Hello</h1></body>
+  </html>
+`
 ```
-Example:
-``` js
-import { fragment, html, body, h1 } from 'javascript-to-html'
-export function generateStaticParams() {
-  return [
-    {
-      year: 2026,
-      slug: "vite-routing"
-    },
-    {
-      year: 2025,
-      slug: 'my-first-post'
-    }
-  ]
-}
+### 2. A plain string
-export default ({ params }) => fragment(
-  '<!doctype html>',
-  html(
-    body(
-      h1(params.slug)
-    )
-  )
-)
+```js
+export default `<html><body><h1>Static as it gets</h1></body></html>`
 ```
----
+### 3. A structured module
-# Catch-All Routes
+Keeps `render`, `data`, and `generateStaticParams` together in one object:
-```
-src/docs/[...slug].ht.js
+```js
+export default {
+  generateStaticParams: () => [{ slug: "hello" }],
+  data: ({ params }) => ({ title: params.slug }),
+  render: ({ data }) => `<html><body><h1>${data.title}</h1></body></html>`,
+}
 ```
-Matches:
+### 4. JSX / TSX
-```
-/docs/api/auth/login
-/docs/guides/rendering/static
-```
-Params:
+Name the file `*.ht.jsx` or `*.ht.tsx` and return JSX — it is rendered
+to **static HTML** at build time with `react-dom/server`:
-```
-params.slug === "api/auth/login"
+```tsx
+// src/index.ht.tsx
+export default function Home() {
+  return (
+    <html lang="en">
+      <head><title>My site</title></head>
+      <body><h1>Hello from TSX</h1></body>
+    </html>
+  )
+}
 ```
----
+JSX pages require `react` and `react-dom` in your project (they are
+optional peer dependencies — string-based pages don't need them).
+Since output is static, event-handler props like `onClick` won't do
+anything in the browser; the dev server warns you if it finds any.
-# Optional Catch-All Routes
+### 5. javascript-to-html
-```
-src/docs/[...slug]?.ht.js
-```
+Prefer composable functions over template strings? The companion
+library [javascript-to-html](https://www.npmjs.com/package/javascript-to-html)
+works great:
-Matches both:
+```js
+import { html, head, title, body, h1 } from 'javascript-to-html'
+export default () =>
+  html({ lang: 'en' },
+    head(title('My website')),
+    body(h1('Hello world'))
+  )
 ```
-/docs
-/docs/getting-started
-/docs/api/auth/login
-```
-Params:
-| URL | params.slug |
-|-----|-------------|
-| `/docs` | "" |
-| `/docs/api` | "api" |
-| `/docs/api/auth` | "api/auth" |
----
-# Route Groups
-Folders wrapped in parentheses are ignored in URLs.
+> If a page's output starts with `<html>`, `<!DOCTYPE html>` is
+> prepended automatically.
-```
-src/(admin)/users.ht.js
-```
+### Render context
-URL:
+Every page function receives one argument:
-```
-/users
-```
+| Property | Type | Description |
+|----------|------|-------------|
+| `params` | `Record<string, string \| string[]>` | Route params for this page |
+| `data`   | `unknown` | Whatever your `data()` returned |
+| `page`   | `object` | Route metadata (`routePath`, `relativePath`, ...) |
+| `dev`    | `boolean` | `true` in the dev server, `false` at build |
 ---
-# Index Routes
+## Routing
-Files named `index.ht.js` map to the parent route.
+Routes come straight from the filesystem:
-```
-src/blog/index.ht.js        -> /blog
-src/blog/[slug]/index.ht.js -> /blog/my-post
-```
+| Feature | File | URL |
+|---------|------|-----|
+| Static routes | `index.ht.js` | `/` |
+| Nested routes | `blog/index.ht.js` | `/blog` |
+| Dynamic routes | `blog/[slug].ht.js` | `/blog/my-post` |
+| Multiple params | `blog/[year]/[slug].ht.js` | `/blog/2026/my-post` |
+| Catch-all | `docs/[...path].ht.js` | `/docs/api/auth/login` |
+| Optional catch-all | `docs/[...path]?.ht.js` | `/docs` and `/docs/anything/below` |
+| Index routes | `products/[id]/index.ht.js` | `/products/iphone-18` |
+| Route groups | `(admin)/users.ht.js` | `/users` |
----
+More specific routes always win: static segments beat dynamic ones,
+dynamic beat catch-alls. Two files generating the same URL is a build
+error, not a silent overwrite.
-# Static Params
+### Static params
-Dynamic routes can export `generateStaticParams`.
+Dynamic routes declare their pages by exporting `generateStaticParams`:
 ```js
+// src/blog/[slug].ht.js
 export function generateStaticParams() {
   return [
-    { slug: "hello-world" },
-    { slug: "vite-routing" }
+    { slug: 'hello-world' },
+    { slug: 'my-first-post' },
   ]
 }
+export default ({ params }) => `
+  <html><body><h1>${params.slug}</h1></body></html>
+`
 ```
+Values can be strings, numbers, or booleans — they are stringified and
+URL-encoded for you. Catch-all params accept arrays (`{ path: ['a', 'b'] }`)
+or slash-separated strings (`{ path: 'a/b' }`).
+A dynamic page that generates zero routes prints a warning so it can't
+silently vanish from your site.
 ---
-# Data Loading
+## Data loading
-Pages can export a `data()` function.
+Export a `data()` function and its result appears as `ctx.data` in your
+render function. It runs at build time (and per-request in dev):
 ```js
-export async function data({ params }) {
-  return { title: params.slug }
+export async function data({ params, dev }) {
+  const res = await fetch(`https://api.example.com/posts/${params.slug}`)
+  return await res.json()
 }
-```
----
+export default ({ data }) => `
+  <html><body>
+    <h1>${data.title}</h1>
+    ${data.body}
+  </body></html>
+`
+```
-# Caching
+### fetchWithCache
-Use `fetchWithCache` for HTTP requests during static generation. Responses are
-cached to avoid repeated network calls across page builds.
+Building 500 pages against the same API? Cache the responses:
 ```js
 import { fetchWithCache } from 'vite-plugin-html-pages'
@@ -371,162 +311,230 @@ import { fetchWithCache } from 'vite-plugin-html-pages'
 export async function data({ params }) {
   const res = await fetchWithCache(
     `https://api.example.com/posts/${params.slug}`,
-    {
-      // fetch API options
-    },
+    { /* standard fetch options */ },
     { maxAge: 3600 }
   )
-  const post = await res.json()
-  return { post }
+  return { post: await res.json() }
 }
 ```
-## Options
 | Option | Description |
 |--------|-------------|
-| `maxAge` | Cache TTL in seconds (default: 3600) |
-| `cacheKey` | Custom cache key (default: hash of URL + method + headers) |
-| `forceRefresh` | Bypass cache and fetch fresh |
+| `maxAge` | Cache TTL in seconds (default: `3600`) |
+| `cacheKey` | Custom cache key (default: hash of URL + method + headers + body) |
+| `forceRefresh` | Bypass the cache and fetch fresh |
 | `cache` | `'auto'` \| `'memory'` \| `'fs'` \| `'none'` |
-## Cache modes
+Cache modes:
-- **`auto`** (default): memory in dev, filesystem in production
-- **`memory`**: in-process cache, cleared when the build process exits
-- **`fs`**: persisted under `node_modules/.cache/vite-plugin-html-pages/fetch/`
-- **`none`**: no caching, always fetches
+- **`auto`** (default) — memory in dev, filesystem in production builds
+- **`memory`** — in-process, cleared when the process exits
+- **`fs`** — persisted in `node_modules/.cache/vite-plugin-html-pages/fetch/`
+- **`none`** — always fetch
-Only `GET` requests are cached by default. For other methods, provide a
-`cacheKey` to enable caching.
+Only `GET` requests are cached by default (pass a `cacheKey` to cache
+other methods), and error responses are never cached — a flaky API
+during one build won't poison the next one.
 ---
-# Layouts
+## TypeScript & typed params
-Reusable layout functions work naturally with HT.js.
+Pages can be written in TypeScript (`.ht.ts` / `.ht.tsx`) with zero
+configuration.
-``` js
-import { fragment, html, head, body } from 'javascript-to-html'
+Helper functions give your page modules full type inference:
-export default (...content) => fragment(
-  '<!doctype html>',
-  html(
-    head(),
-    body(
-      ...content
-    )
-  )
-)
+```ts
+// src/blog/[slug].ht.ts
+import { definePageModule } from 'vite-plugin-html-pages/page'
+export default definePageModule({
+  generateStaticParams: () => [{ slug: 'hello' }],
+  data: ({ params }) => ({ title: params.slug }),
+  render: ({ data }) => `<html><body><h1>${data.title}</h1></body></html>`,
+})
 ```
----
+Individual helpers (`definePage`, `defineData`, `defineStaticParams`)
+are also exported. At build time this import is transparently swapped
+for a **per-route generated module** whose `PageParams` are inferred
+from the filename: `[slug]` → `{ slug: string }`, `[...path]` →
+`{ path: string[] }`, `[...path]?` → `{ path?: string[] }`.
-# Plugin Options
-| Option | Description |
-|------|------|
-| `pagesDir` | root directory for pages |
-| `include` | page glob |
-| `exclude` | excluded files |
-| `cleanUrls` | `/page/index.html` instead of `/page.html` |
-| `renderConcurrency` | parallel rendering |
-| `renderBatchSize` | batch size |
-| `debug` | enable debug logging |
-| `site` | base URL for sitemap |
-| `rss` | RSS configuration |
+Matching type declarations are generated into
+`.vite-plugin-html-pages/types/` whenever the dev server or a build
+runs — add that folder to `.gitignore`.
 ---
-# Debug Mode
+## Assets & styling
-Enable debug logging when troubleshooting.
+Reference assets from your HTML with root-relative URLs and the plugin
+handles the rest:
 ```js
-htmlPages({
-  debug: true
-})
+export default () => `
+  <html>
+    <head>
+      <link rel="stylesheet" href="/styles.css">
+      <script type="module" src="/main.js"></script>
+    </head>
+    <body>...</body>
+  </html>
+`
+```
+At build time:
+- **Referenced JS / TS / CSS is bundled** with esbuild — imports are
+  inlined, output is minified, and `.ts` files compile to `.js`.
+- **Unreferenced code files are not emitted.** A helper like
+  `src/lib/api.ts` that you only import from `data()` stays out of
+  `dist/` — server-only code (and its secrets) never ships by accident.
+- **Everything else is copied** (images, fonts, videos, ...), so CSS
+  `url()` references keep working.
+- **`public/` behaves like normal Vite** — copied verbatim.
+In dev, the same URLs are served through Vite's transform pipeline, so
+TypeScript and CSS work identically without a build.
+### Missing-asset validation
+Every generated page is checked: a `<script src="/x.js">` or stylesheet
+`href` pointing at a file that exists in neither `src/` nor `public/`
+**fails the build** with the exact paths that were checked. Prefer a
+warning instead?
+```js
+htmlPages({ missingAssets: 'warn' })
 ```
-Example output:
+---
+## Dev server
-    [vite-plugin-html-pages] discovered entries [...]
-    [vite-plugin-html-pages] dev pages [...]
-    [vite-plugin-html-pages] render bundle ...
+`vite dev` gives you the real site, not an approximation:
-This helps diagnose routing or build issues without modifying plugin
-code.
+- Pages render **on request** through Vite's SSR module runner — edit a
+  page, its `data()`, or any imported module and reload.
+- File changes inside your pages directory trigger an automatic
+  **full-reload** in the browser.
+- Errors show a **source-mapped code frame** in the terminal pointing
+  at the exact line in your page — the server stays alive while you fix it.
----
+```
+── PAGE RELOAD ERROR ───────────────────── src/index.ht.js:6:20
-# Automatic Sitemap
+ReferenceError: title is not defined
-A `sitemap.xml` is generated automatically.
+> 6 │     head(title('My website')),
+    │          ^
-```
-dist/sitemap.xml
+Fix the error and save again.
+Watching for file changes...
 ```
 ---
-# Optional RSS Feed
+## Generated extras
+### 404 page
+Create `src/404.ht.js` and it's emitted as `dist/404.html` (the
+convention GitHub Pages, Netlify, and Cloudflare Pages all understand).
+No 404 page? A clean default is generated.
+### Sitemap
+Set your site URL and `dist/sitemap.xml` is generated from all static
+routes, correctly escaped:
+```js
+htmlPages({ site: 'https://example.com' })
+```
+### RSS feed
 ```js
 htmlPages({
   rss: {
-    site: "https://example.com",
-    title: "My Blog",
-    description: "Latest posts",
-    routePrefix: "/blog"
+    site: 'https://example.com',
+    title: 'My Blog',
+    description: 'Latest posts',
+    routePrefix: '/blog',   // which routes become feed items
   }
 })
 ```
-Produces:
+Produces `dist/rss.xml` with an item for every page under `routePrefix`.
-```
-dist/rss.xml
+---
+## Plugin options
+```js
+htmlPages({
+  pagesDir: 'src',
+  cleanUrls: true,
+  site: 'https://example.com',
+  missingAssets: 'error',
+  debug: false,
+})
 ```
----
+| Option | Default | Description |
+|--------|---------|-------------|
+| `pagesDir` | `'src'` | Directory containing pages and assets |
+| `pageExtensions` | `['.ht.js', '.html.js', ...]` | Which file suffixes are pages |
+| `include` | derived from `pagesDir` | Custom glob(s) for page discovery |
+| `exclude` | `[]` | Glob(s) to exclude from discovery |
+| `root` | Vite root | Override the project root |
+| `cleanUrls` | `true` | `/about/index.html` (`/about`) instead of `/about.html` |
+| `site` | — | Base URL; enables `sitemap.xml` |
+| `rss` | — | RSS config (`site`, `title`, `description`, `routePrefix`) |
+| `missingAssets` | `'error'` | `'error'` or `'warn'` for broken asset references |
+| `mapOutputPath` | — | `(page) => string` to customize output filenames |
+| `renderConcurrency` | `8` | Pages rendered in parallel |
+| `renderBatchSize` | `max(concurrency, 32)` | Pages per render batch |
+| `debug` | `false` | Verbose logging of discovery, routing, and emission |
-# Performance
+### Performance
-Large sites can increase concurrency:
+Large sites can raise the parallelism:
 ```js
 htmlPages({
   renderConcurrency: 16,
-  renderBatchSize: 128
+  renderBatchSize: 128,
 })
 ```
 ---
-# Comparison
+## Comparison
-| Tool | Focus |
-|-----|-----|
-| Astro | component‑based SSG |
-| Next.js | React SSR framework |
-| vite-plugin-html-pages | minimal HTML SSG for Vite |
----
+| Tool | What it is |
+|------|------------|
+| Astro | Component-based SSG with its own compiler and islands |
+| Next.js | Full React framework with SSR/ISR |
+| Eleventy | Template-language SSG (Nunjucks, Liquid, ...) |
+| **vite-plugin-html-pages** | **Functions returning HTML, powered by plain Vite** |
-# Use Cases
+If you want components, hydration, and a framework — use a framework.
+If you want HTML files out of JavaScript functions with the Vite dev
+experience, this is the smallest tool that does the whole job.
-`vite-plugin-html-pages` works well for:
+## Good fits
--   **Vite static site generation**
--   **File-based routing with Vite**
--   **Generating static HTML with Vite**
--   **Vite blog generators**
--   **Documentation sites**
--   **Minimal static site generators**
--   **HTML‑first Vite projects**
+- Marketing and landing pages
+- Blogs and documentation sites
+- HTML-first projects with a sprinkle of JS
+- API-driven static sites (with `fetchWithCache`)
+- Any site where "view source" should show exactly what you wrote
 ---
-# License
+## License
 MIT