vite-plugin-htjs-pages 0.2.0

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "vite-plugin-htjs-pages",
+  "author": "Paul Browne",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Small HT.js pages plugin for Vite with dynamic routes, catch-all routes, and static params",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "vite": "^5 || ^6"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.3",
+    "p-limit": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "rollup": "^4.34.6",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vite": "^6.0.0"
+  }
+}

package/src/dev-server.ts

@@ -0,0 +1,34 @@
+import type { ViteDevServer } from 'vite';
+import { renderPage } from './render-runtime';
+import { routeMatch } from './route-utils';
+import type { HtPageInfo, HtPageModule } from './types';
+
+export function installDevServer(args: {
+  server: ViteDevServer;
+  getPages: () => HtPageInfo[];
+}): void {
+  const { server, getPages } = args;
+
+  server.middlewares.use(async (req, res, next) => {
+    if (!req.url || req.method !== 'GET') return next();
+
+    const pathname = req.url.split('?')[0];
+    const pages = getPages();
+
+    for (const page of pages) {
+      const params = routeMatch(page.routePattern, pathname);
+      if (!params) continue;
+
+      const mod = (await server.ssrLoadModule(page.entryPath)) as HtPageModule;
+      const resolvedPage = { ...page, routePath: pathname || '/', params };
+      const html = await renderPage(resolvedPage, mod, true);
+
+      res.statusCode = 200;
+      res.setHeader('Content-Type', 'text/html; charset=utf-8');
+      res.end(html);
+      return;
+    }
+
+    next();
+  });
+}

package/src/discover.ts

@@ -0,0 +1,38 @@
+import path from 'node:path';
+import fg from 'fast-glob';
+import { normalizeFsPath, toPosix } from './path-utils';
+import { getParamNames, isDynamicPage, toRoutePattern } from './route-utils';
+import type { HtPageInfo, HtPagesPluginOptions } from './types';
+
+export async function discoverEntryPages(root: string, options: HtPagesPluginOptions): Promise<HtPageInfo[]> {
+  const include = Array.isArray(options.include) ? options.include : [options.include ?? 'src/**/*.ht.js'];
+  const exclude = Array.isArray(options.exclude) ? options.exclude : options.exclude ? [options.exclude] : [];
+  const pagesDir = options.pagesDir ?? 'src';
+
+  const files = await fg(include, {
+    cwd: root,
+    ignore: exclude,
+    absolute: true,
+  });
+
+  return files.sort().map((absolutePath) => {
+    const entryPath = normalizeFsPath(absolutePath);
+    const relativePath = toPosix(path.relative(root, entryPath));
+    const relativeFromPagesDir = toPosix(path.relative(path.join(root, pagesDir), entryPath));
+    const dynamic = isDynamicPage(relativeFromPagesDir);
+    const routePattern = toRoutePattern(relativeFromPagesDir);
+
+    return {
+      id: entryPath,
+      entryPath,
+      absolutePath: entryPath,
+      relativePath,
+      routePattern,
+      routePath: routePattern,
+      fileName: '',
+      dynamic,
+      paramNames: getParamNames(relativeFromPagesDir),
+      params: {},
+    };
+  });
+}

package/src/errors.ts

@@ -0,0 +1,19 @@
+import type { HtPageInfo } from './types';
+
+export function invalidHtmlReturn(page: HtPageInfo, value: unknown): Error {
+  return new Error(
+    `[vite-plugin-ht-pages] Page "${page.relativePath}" must resolve to an HTML string, got ${typeof value}`,
+  );
+}
+
+export function pageError(page: HtPageInfo, cause: unknown): Error {
+  const message = `[vite-plugin-ht-pages] Failed to render ${page.relativePath} (${page.routePath})`;
+  if (cause instanceof Error && cause.stack) {
+    const err = new Error(message);
+    err.stack = `${err.stack}
+Caused by:
+${cause.stack}`;
+    return err;
+  }
+  return new Error(message);
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { htPages } from './plugin';
+export type {
+  HtPageInfo,
+  HtPageModule,
+  HtPagesPluginOptions,
+  HtPageRenderContext,
+  StaticParamRecord,
+} from './types';

package/src/manifest.ts

@@ -0,0 +1,25 @@
+import type { HtPageInfo } from './types';
+
+function js(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+export function createManifestModule(entries: HtPageInfo[]): string {
+  const imports = entries
+    .map((page, i) => `import * as page${i} from ${js(page.entryPath)};`)
+    .join('');
+
+  const records = entries
+    .map((page, i) => `{
+  page: ${js(page)},
+  mod: page${i}
+}`)
+    .join(',');
+
+  return `${imports}
+
+export const manifest = [
+${records}
+];
+`;
+}

package/src/page-index.ts

@@ -0,0 +1,44 @@
+import { compareRoutePriority, expandStaticPaths, fileNameFromRoute } from './route-utils';
+import type { HtPageInfo, HtPageModule, StaticParamRecord } from './types';
+
+export async function buildPageIndex(args: {
+  entries: HtPageInfo[];
+  modulesByEntry: Map<string, HtPageModule>;
+  cleanUrls: boolean;
+}): Promise<HtPageInfo[]> {
+  const { entries, modulesByEntry, cleanUrls } = args;
+  const pages: HtPageInfo[] = [];
+
+  for (const entry of entries) {
+    const mod = modulesByEntry.get(entry.entryPath) ?? {};
+
+    if (entry.dynamic) {
+      const rows = mod.generateStaticParams ? await mod.generateStaticParams() : [];
+      pages.push(
+        ...expandStaticPaths(
+          {
+            id: entry.id,
+            entryPath: entry.entryPath,
+            absolutePath: entry.absolutePath,
+            relativePath: entry.relativePath,
+            routePattern: entry.routePattern,
+            dynamic: entry.dynamic,
+            paramNames: entry.paramNames,
+          } as Omit<HtPageInfo, 'routePath' | 'fileName' | 'params'>,
+          rows as StaticParamRecord[],
+          cleanUrls,
+        ),
+      );
+    } else {
+      pages.push({
+        ...entry,
+        routePath: entry.routePattern,
+        fileName: fileNameFromRoute(entry.routePattern, cleanUrls),
+        params: {},
+      });
+    }
+  }
+
+  pages.sort((a, b) => compareRoutePriority(a.routePattern, b.routePattern));
+  return pages;
+}

package/src/path-utils.ts

@@ -0,0 +1,20 @@
+import path from 'node:path';
+
+export function toPosix(p: string): string {
+  return p.split(path.sep).join('/');
+}
+
+export function stripHtSuffix(file: string): string {
+  return file.replace(/\.ht\.js$/i, '');
+}
+
+export function normalizeRoutePath(p: string): string {
+  let out = p.startsWith('/') ? p : `/${p}`;
+  out = out.replace(/\/+/g, '/');
+  if (out !== '/' && out.endsWith('/')) out = out.slice(0, -1);
+  return out;
+}
+
+export function normalizeFsPath(p: string): string {
+  return toPosix(path.resolve(p));
+}

package/src/plugin.ts

@@ -0,0 +1,154 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createHash } from 'node:crypto';
+import pLimit from 'p-limit';
+import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
+import { discoverEntryPages } from './discover';
+import { installDevServer } from './dev-server';
+import { buildPageIndex } from './page-index';
+import { buildRenderBundle } from './render-bundle';
+import { renderPage } from './render-runtime';
+import type { HtPageInfo, HtPageModule, HtPagesPluginOptions } from './types';
+
+function chunkArray<T>(items: T[], size: number): T[][] {
+  const out: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    out.push(items.slice(i, i + size));
+  }
+  return out;
+}
+
+function createEntriesKey(entries: HtPageInfo[]): string {
+  const raw = entries
+    .map((e) => `${e.entryPath}|${e.routePattern}|${e.dynamic}`)
+    .join('\n');
+
+  return createHash('sha256').update(raw).digest('hex');
+}
+
+async function importManifest(bundlePath: string): Promise<Array<{ page: HtPageInfo; mod: HtPageModule }>> {
+  const mod = await import(pathToFileURL(bundlePath).href + `?t=${Date.now()}`);
+  return mod.manifest as Array<{ page: HtPageInfo; mod: HtPageModule }>;
+}
+
+export function htPages(options: HtPagesPluginOptions = {}): Plugin {
+  let root = process.cwd();
+  let server: ViteDevServer | null = null;
+  let config: ResolvedConfig;
+  let devPages: HtPageInfo[] = [];
+  let cachedManifestKey: string | null = null;
+  let cachedBundlePath: string | null = null;
+  const cleanUrls = options.cleanUrls ?? true;
+
+  async function loadDevPages(): Promise<HtPageInfo[]> {
+    const entries = await discoverEntryPages(root, options);
+    const modulesByEntry = new Map<string, HtPageModule>();
+
+    if (!server) return [];
+
+    for (const entry of entries) {
+      const mod = (await server.ssrLoadModule(entry.entryPath)) as HtPageModule;
+      modulesByEntry.set(entry.entryPath, mod);
+    }
+
+    devPages = await buildPageIndex({
+      entries,
+      modulesByEntry,
+      cleanUrls,
+    });
+
+    return devPages;
+  }
+
+  return {
+    name: 'vite-plugin-ht-pages',
+
+    configResolved(resolved) {
+      config = resolved;
+      root = resolved.root;
+    },
+
+    async buildStart() {
+      const entries = await discoverEntryPages(root, options);
+      for (const entry of entries) {
+        this.addWatchFile(entry.entryPath);
+      }
+    },
+
+    configureServer(_server) {
+      server = _server;
+
+      installDevServer({
+        server,
+        getPages: () => devPages,
+      });
+
+      loadDevPages().catch((error) => {
+        server?.config.logger.error(String(error));
+      });
+
+      return () => {
+        server = null;
+      };
+    },
+
+    async handleHotUpdate() {
+      if (server) {
+        await loadDevPages();
+      }
+      return undefined;
+    },
+
+    async generateBundle() {
+      const entries = await discoverEntryPages(root, options);
+      const cacheDir = path.join(root, 'node_modules/.cache/vite-plugin-ht-pages');
+
+      const entriesKey = createEntriesKey(entries);
+
+      let bundlePath: string;
+      if (cachedBundlePath && cachedManifestKey === entriesKey) {
+        bundlePath = cachedBundlePath;
+      } else {
+        bundlePath = await buildRenderBundle({
+          entries,
+          cacheDir,
+          ssrPlugins: options.ssrPlugins,
+        });
+        cachedManifestKey = entriesKey;
+        cachedBundlePath = bundlePath;
+      }
+
+      const manifest = await importManifest(bundlePath);
+      const modulesByEntry = new Map<string, HtPageModule>();
+      for (const rec of manifest) {
+        modulesByEntry.set(rec.page.entryPath, rec.mod);
+      }
+
+      const pages = await buildPageIndex({
+        entries,
+        modulesByEntry,
+        cleanUrls,
+      });
+
+      const limit = pLimit(options.renderConcurrency ?? 8);
+      const batchSize = options.renderBatchSize ?? Math.max(options.renderConcurrency ?? 8, 32);
+
+      for (const batch of chunkArray(pages, batchSize)) {
+        await Promise.all(
+          batch.map((page) =>
+            limit(async () => {
+              const mod = modulesByEntry.get(page.entryPath);
+              if (!mod) throw new Error(`Missing module for page entry: ${page.entryPath}`);
+              const html = await renderPage(page, mod, false);
+              this.emitFile({
+                type: 'asset',
+                fileName: options.mapOutputPath?.(page) ?? page.fileName,
+                source: html,
+              });
+            }),
+          ),
+        );
+      }
+    },
+  };
+}

package/src/render-bundle.ts

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { rollup, type Plugin as RollupPlugin } from 'rollup';
+import { createManifestModule } from './manifest';
+import type { HtPageInfo } from './types';
+
+const VIRTUAL_MANIFEST_ID = '\0virtual:ht-pages-manifest';
+
+export async function buildRenderBundle(args: {
+  entries: HtPageInfo[];
+  cacheDir: string;
+  ssrPlugins?: RollupPlugin[];
+}): Promise<string> {
+  const { entries, cacheDir, ssrPlugins = [] } = args;
+  const source = createManifestModule(entries);
+  const hash = createHash('sha256').update(source).digest('hex').slice(0, 12);
+  const bundlePath = path.join(cacheDir, `render-${hash}.mjs`);
+
+  await fs.mkdir(cacheDir, { recursive: true });
+
+  const bundle = await rollup({
+    input: VIRTUAL_MANIFEST_ID,
+    plugins: [
+      {
+        name: 'ht-pages:virtual-manifest',
+        resolveId(id) {
+          return id === VIRTUAL_MANIFEST_ID ? id : null;
+        },
+        load(id) {
+          return id === VIRTUAL_MANIFEST_ID ? source : null;
+        },
+      },
+      ...ssrPlugins,
+    ],
+    treeshake: true,
+  });
+
+  const { output } = await bundle.generate({
+    format: 'esm',
+    exports: 'named',
+    inlineDynamicImports: true,
+  });
+
+  const chunk = output.find((item) => item.type === 'chunk');
+  if (!chunk || chunk.type !== 'chunk') {
+    throw new Error('Failed to generate HT pages render bundle.');
+  }
+
+  await fs.writeFile(bundlePath, chunk.code, 'utf8');
+  await bundle.close();
+  return bundlePath;
+}

package/src/render-runtime.ts

@@ -0,0 +1,27 @@
+import { invalidHtmlReturn, pageError } from './errors';
+import type { HtPageInfo, HtPageModule, HtPageRenderContext } from './types';
+
+export async function renderPage(page: HtPageInfo, mod: HtPageModule, dev = false): Promise<string> {
+  const ctx: HtPageRenderContext = {
+    page,
+    params: page.params,
+    dev,
+  };
+
+  try {
+    if (typeof mod.data === 'function') {
+      ctx.data = await mod.data(ctx);
+    }
+
+    const entry = mod.default;
+    const html = typeof entry === 'function' ? await entry(ctx) : entry;
+
+    if (typeof html !== 'string') {
+      throw invalidHtmlReturn(page, html);
+    }
+
+    return html;
+  } catch (error) {
+    throw pageError(page, error);
+  }
+}

package/src/route-utils.ts

@@ -0,0 +1,114 @@
+import { normalizeRoutePath, stripHtSuffix, toPosix } from './path-utils';
+import type { HtPageInfo, StaticParamRecord } from './types';
+
+const DYNAMIC_SEGMENT_RE = /\[([A-Za-z0-9_]+)\]/g;
+const CATCH_ALL_SEGMENT_RE = /\[\.\.\.([A-Za-z0-9_]+)\]/g;
+const ANY_PARAM_RE = /\[(?:\.\.\.)?([A-Za-z0-9_]+)\]/g;
+
+export function getParamNames(relativeFromPagesDir: string): string[] {
+  return [...relativeFromPagesDir.matchAll(ANY_PARAM_RE)].map((m) => m[1]);
+}
+
+export function isDynamicPage(relativeFromPagesDir: string): boolean {
+  return ANY_PARAM_RE.test(relativeFromPagesDir);
+}
+
+export function toRoutePattern(relativeFromPagesDir: string): string {
+  const noExt = stripHtSuffix(toPosix(relativeFromPagesDir));
+  const raw = noExt
+    .replace(/(^|\/)index$/i, '$1')
+    .replace(CATCH_ALL_SEGMENT_RE, '*:$1')
+    .replace(DYNAMIC_SEGMENT_RE, ':$1');
+  return normalizeRoutePath(raw || '/');
+}
+
+export function fillParams(pattern: string, params: Record<string, string>): string {
+  return pattern
+    .replace(/\*:([A-Za-z0-9_]+)/g, (_, key) => {
+      if (!(key in params)) throw new Error(`Missing catch-all route param "${key}"`);
+      return String(params[key])
+        .split('/')
+        .map((part) => encodeURIComponent(part))
+        .join('/');
+    })
+    .replace(/:([A-Za-z0-9_]+)/g, (_, key) => {
+      if (!(key in params)) throw new Error(`Missing route param "${key}"`);
+      return encodeURIComponent(params[key]);
+    });
+}
+
+export function fileNameFromRoute(routePath: string, cleanUrls: boolean): string {
+  const normalized = normalizeRoutePath(routePath);
+  if (normalized === '/') return 'index.html';
+  const base = normalized.slice(1);
+  return cleanUrls ? `${base}/index.html` : `${base}.html`;
+}
+
+export function expandStaticPaths(
+  basePage: Omit<HtPageInfo, 'routePath' | 'fileName' | 'params'>,
+  rows: StaticParamRecord[],
+  cleanUrls: boolean,
+): HtPageInfo[] {
+  return rows.map((row) => {
+    const params = Object.fromEntries(
+      Object.entries(row).map(([k, v]) => [k, String(v)]),
+    );
+    const routePath = fillParams(basePage.routePattern, params);
+    return {
+      ...basePage,
+      routePath,
+      fileName: fileNameFromRoute(routePath, cleanUrls),
+      params,
+    };
+  });
+}
+
+export function routeMatch(pattern: string, urlPath: string): Record<string, string> | null {
+  const a = normalizeRoutePath(pattern).split('/').filter(Boolean);
+  const b = normalizeRoutePath(urlPath).split('/').filter(Boolean);
+  const params: Record<string, string> = {};
+
+  for (let i = 0, j = 0; i < a.length; i++, j++) {
+    const seg = a[i];
+
+    if (seg.startsWith('*:')) {
+      params[seg.slice(2)] = b.slice(j).map(decodeURIComponent).join('/');
+      return params;
+    }
+
+    if (j >= b.length) return null;
+
+    if (seg.startsWith(':')) {
+      params[seg.slice(1)] = decodeURIComponent(b[j]);
+      continue;
+    }
+
+    if (seg !== b[j]) return null;
+  }
+
+  return a.length === b.length ? params : null;
+}
+
+export function compareRoutePriority(a: string, b: string): number {
+  const aSegs = normalizeRoutePath(a).split('/').filter(Boolean);
+  const bSegs = normalizeRoutePath(b).split('/').filter(Boolean);
+  const len = Math.max(aSegs.length, bSegs.length);
+
+  for (let i = 0; i < len; i++) {
+    const aa = aSegs[i];
+    const bb = bSegs[i];
+
+    if (aa == null) return -1;
+    if (bb == null) return 1;
+
+    const aCatchAll = aa.startsWith('*:');
+    const bCatchAll = bb.startsWith('*:');
+    if (aCatchAll !== bCatchAll) return aCatchAll ? 1 : -1;
+
+    const aDynamic = aa.startsWith(':');
+    const bDynamic = bb.startsWith(':');
+    if (aDynamic !== bDynamic) return aDynamic ? 1 : -1;
+  }
+
+  return aSegs.length - bSegs.length;
+}

package/src/types.ts

@@ -0,0 +1,41 @@
+export interface StaticParamRecord {
+    [key: string]: string | number | boolean;
+  }
+  
+  export interface HtPageInfo {
+    id: string;
+    entryPath: string;
+    absolutePath: string;
+    relativePath: string;
+    routePattern: string;
+    routePath: string;
+    fileName: string;
+    dynamic: boolean;
+    paramNames: string[];
+    params: Record<string, string>;
+  }
+  
+  export interface HtPageRenderContext {
+    page: HtPageInfo;
+    params: Record<string, string>;
+    data?: unknown;
+    dev?: boolean;
+  }
+  
+  export interface HtPageModule {
+    default?: string | ((ctx: HtPageRenderContext) => string | Promise<string>);
+    data?: (ctx: HtPageRenderContext) => unknown | Promise<unknown>;
+    generateStaticParams?: () => StaticParamRecord[] | Promise<StaticParamRecord[]>;
+  }
+  
+  export interface HtPagesPluginOptions {
+    root?: string;
+    include?: string | string[];
+    exclude?: string | string[];
+    pagesDir?: string;
+    renderConcurrency?: number;
+    renderBatchSize?: number;
+    cleanUrls?: boolean;
+    ssrPlugins?: import('rollup').Plugin[];
+    mapOutputPath?: (page: HtPageInfo) => string;
+  }

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+    "compilerOptions": {
+      "target": "ES2020",
+      "module": "ESNext",
+      "moduleResolution": "Bundler",
+      "strict": true,
+      "declaration": true,
+      "outDir": "dist",
+      "skipLibCheck": true,
+      "esModuleInterop": true,
+      "types": ["node"]
+    },
+    "include": ["src"]
+  }

package/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+});