vite-plugin-html-pages 1.0.0

package/src/plugin.ts

@@ -0,0 +1,272 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import pLimit from 'p-limit';
+import type { Plugin, ViteDevServer } from 'vite';
+
+import { discoverEntryPages } from './discover';
+import { installDevServer } from './dev-server';
+import { buildPageIndex } from './page-index';
+import { renderPage } from './render-runtime';
+
+import type { HtPageInfo, HtPageModule, HtPagesPluginOptions } from './types';
+import {
+  PLUGIN_NAME,
+  VIRTUAL_BUILD_ENTRY_ID,
+} from './constants';
+
+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;
+}
+
+async function importPageModule(entryPath: string): Promise<HtPageModule> {
+  const mod = await import(pathToFileURL(entryPath).href + `?t=${Date.now()}`);
+  return mod as HtPageModule;
+}
+
+async function warnIfNotEsm(root: string): Promise<void> {
+  try {
+    const pkgPath = path.join(root, 'package.json');
+    const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+
+    if (pkg.type !== 'module') {
+      console.warn(
+        `[${PLUGIN_NAME}] Tip: add "type": "module" to package.json to avoid Node ESM warnings.`,
+      );
+    }
+  } catch {
+      // ignore
+  }
+}
+
+export function htPages(options: HtPagesPluginOptions = {}): Plugin {
+  let root = process.cwd();
+  let server: ViteDevServer | null = null;
+  let devPages: HtPageInfo[] = [];
+
+  const cleanUrls = options.cleanUrls ?? true;
+
+  function logDebug(enabled: boolean | undefined, ...args: unknown[]) {
+    if (!enabled) return;
+    console.log(`[${PLUGIN_NAME}]`, ...args);
+  }
+
+  async function loadDevPages(): Promise<HtPageInfo[]> {
+    const entries = await discoverEntryPages(root, options);
+    const modulesByEntry = new Map<string, HtPageModule>();
+
+    logDebug(
+      options.debug,
+      'discovered entries',
+      entries.map((e) => e.relativePath),
+    );
+
+    if (!server) return [];
+
+    for (const entry of entries) {
+      const mod = (await server.ssrLoadModule(
+        `/${entry.relativePath}`,
+      )) as HtPageModule;
+
+      modulesByEntry.set(entry.entryPath, mod);
+    }
+
+    devPages = await buildPageIndex({
+      entries,
+      modulesByEntry,
+      cleanUrls,
+    });
+
+    logDebug(
+      options.debug,
+      'dev pages',
+      devPages.map((p) => `${p.routePath} -> ${p.relativePath}`),
+    );
+
+    return devPages;
+  }
+
+  async function buildPagesPipeline() {
+    const entries = await discoverEntryPages(root, options);
+    const modulesByEntry = new Map<string, HtPageModule>();
+
+    for (const entry of entries) {
+      const mod = await importPageModule(entry.entryPath);
+      modulesByEntry.set(entry.entryPath, mod);
+    }
+
+    const pages = await buildPageIndex({
+      entries,
+      modulesByEntry,
+      cleanUrls,
+    });
+
+    return { entries, modulesByEntry, pages };
+  }
+
+  return {
+    name: PLUGIN_NAME,
+
+    config(userConfig, env) {
+      if (env.command !== 'build') return;
+
+      const hasExplicitInput = userConfig.build?.rollupOptions?.input != null;
+      if (hasExplicitInput) return;
+
+      return {
+        build: {
+          rollupOptions: {
+            input: VIRTUAL_BUILD_ENTRY_ID,
+          },
+        },
+      };
+    },
+
+    resolveId(id) {
+      if (id === VIRTUAL_BUILD_ENTRY_ID) return id;
+      return null;
+    },
+
+    load(id) {
+      if (id === VIRTUAL_BUILD_ENTRY_ID) {
+        return 'export default {};';
+      }
+      return null;
+    },
+
+    configResolved(resolved) {
+      root = resolved.root;
+      void warnIfNotEsm(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: async () => {
+          if (devPages.length > 0) return devPages;
+          return loadDevPages();
+        },
+        getEntries: async () => discoverEntryPages(root, options),
+      });
+
+      loadDevPages().catch((error) => {
+        server?.config.logger.error(
+          `[${PLUGIN_NAME}] loadDevPages failed: ${
+            error instanceof Error ? error.stack ?? error.message : String(error)
+          }`,
+        );
+      });
+    },
+
+    async handleHotUpdate(ctx) {
+      if (!server) return;
+
+      if (!ctx.file.endsWith('.ht.js')) {
+        return;
+      }
+
+      logDebug(options.debug, 'page updated', ctx.file);
+
+      await loadDevPages();
+      return undefined;
+    },
+
+    async generateBundle(_, bundle) {
+      const { modulesByEntry, pages } = await buildPagesPipeline();
+
+      logDebug(
+        options.debug,
+        'emitting pages',
+        pages.map((p) => p.fileName),
+      );
+
+      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(
+                  `[${PLUGIN_NAME}] 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,
+              });
+            }),
+          ),
+        );
+      }
+
+      const sitemapBase = options.site ?? '';
+      const sitemapRoutes = [...new Set(pages.map((p) => p.routePath))].filter(
+        (route) => !route.includes(':') && !route.includes('*'),
+      );
+
+      if (sitemapRoutes.length > 0) {
+        const sitemap = `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${sitemapRoutes
+          .map((route) => `  <url><loc>${sitemapBase}${route}</loc></url>`)
+          .join('\n')}\n</urlset>\n`;
+
+        this.emitFile({
+          type: 'asset',
+          fileName: 'sitemap.xml',
+          source: sitemap,
+        });
+      }
+
+      if (options.rss?.site) {
+        const routePrefix = options.rss.routePrefix ?? '/blog';
+
+        const rssItems = pages
+          .filter((page) => page.routePath.startsWith(routePrefix))
+          .map((page) => {
+            const url = `${options.rss!.site}${page.routePath}`;
+            return `  <item>\n    <title>${page.routePath}</title>\n    <link>${url}</link>\n    <guid>${url}</guid>\n  </item>`;
+          })
+          .join('\n');
+
+        const rss = `<?xml version="1.0" encoding="UTF-8"?>\n<rss version="2.0">\n<channel>\n  <title>${options.rss.title ?? PLUGIN_NAME}</title>\n  <link>${options.rss.site}</link>\n  <description>${options.rss.description ?? 'RSS feed'}</description>\n${rssItems}\n</channel>\n</rss>\n`;
+
+        this.emitFile({
+          type: 'asset',
+          fileName: 'rss.xml',
+          source: rss,
+        });
+      }
+
+      for (const [fileName, output] of Object.entries(bundle)) {
+        if (
+          output.type === 'chunk' &&
+          output.facadeModuleId === VIRTUAL_BUILD_ENTRY_ID
+        ) {
+          delete bundle[fileName];
+        }
+      }
+    },
+  };
+}

package/src/render-bundle.ts

@@ -0,0 +1,92 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import type { Plugin as RollupPlugin } from 'rollup';
+
+import { createManifestModule } from './manifest';
+import type { HtPageInfo } from './types';
+import { PLUGIN_NAME, VIRTUAL_MANIFEST_ID } from './constants';
+
+async function createRenderBundleHash(
+  entries: HtPageInfo[],
+  manifestSource: string,
+): Promise<string> {
+  const hash = createHash('sha256');
+  hash.update(manifestSource);
+
+  for (const entry of entries) {
+    hash.update(entry.entryPath);
+    const source = await fs.readFile(entry.entryPath, 'utf8');
+    hash.update(source);
+  }
+
+  return hash.digest('hex').slice(0, 12);
+}
+
+export async function buildRenderBundle(args: {
+  entries: HtPageInfo[];
+  cacheDir: string;
+  ssrPlugins?: RollupPlugin[];
+}): Promise<string> {
+  const { entries, cacheDir, ssrPlugins = [] } = args;
+
+  const [{ rollup }, { nodeResolve }] = await Promise.all([
+    import('rollup'),
+    import('@rollup/plugin-node-resolve'),
+  ]);
+
+  const manifestSource = createManifestModule(entries);
+  const hash = await createRenderBundleHash(entries, manifestSource);
+  const bundlePath = path.join(cacheDir, `render-${hash}.mjs`);
+
+  await fs.mkdir(cacheDir, { recursive: true });
+
+  try {
+    await fs.access(bundlePath);
+    return bundlePath;
+  } catch {
+    // cache miss
+  }
+
+  const bundle = await rollup({
+    input: VIRTUAL_MANIFEST_ID,
+    plugins: [
+      {
+        name: `${PLUGIN_NAME}:virtual-manifest`,
+        resolveId(id) {
+          return id === VIRTUAL_MANIFEST_ID ? id : null;
+        },
+        load(id) {
+          return id === VIRTUAL_MANIFEST_ID ? manifestSource : null;
+        },
+      },
+      nodeResolve({
+        preferBuiltins: true,
+        exportConditions: ['node'],
+      }),
+      ...ssrPlugins,
+    ],
+    treeshake: true,
+  });
+
+  try {
+    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(
+        `[${PLUGIN_NAME}] Failed to generate HT pages render bundle.`,
+      );
+    }
+
+    await fs.writeFile(bundlePath, chunk.code, 'utf8');
+    return bundlePath;
+  } finally {
+    await bundle.close();
+  }
+}

package/src/render-runtime.ts

@@ -0,0 +1,36 @@
+import { invalidHtmlReturn, pageError, missingDefaultExport } 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;
+
+    if (entry == null) {
+      throw missingDefaultExport(page);
+    }
+
+    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,182 @@
+import { normalizeRoutePath, stripHtSuffix, toPosix } from './path-utils';
+import type { HtPageInfo, StaticParamRecord } from './types';
+
+function safeDecodeURIComponent(str: string): string {
+  try {
+    return decodeURIComponent(str);
+  } catch {
+    return str;
+  }
+}
+
+const DYNAMIC_SEGMENT_RE = /\[([A-Za-z0-9_]+)\]/g;
+const CATCH_ALL_SEGMENT_RE = /\[\.\.\.([A-Za-z0-9_]+)\]/g;
+const OPTIONAL_CATCH_ALL_SEGMENT_RE = /\[\.\.\.([A-Za-z0-9_]+)\]\?/g;
+const ANY_PARAM_RE = /\[(?:\.\.\.)?([A-Za-z0-9_]+)\]\??/g;
+const ROUTE_GROUP_RE = /(^|\/)\(([^)]+)\)(?=\/|$)/g;
+
+export function getParamNames(relativeFromPagesDir: string): string[] {
+  return [...relativeFromPagesDir.matchAll(ANY_PARAM_RE)].map((m) => m[1]);
+}
+
+export function isDynamicPage(relativeFromPagesDir: string): boolean {
+  return /\[(?:\.\.\.)?[A-Za-z0-9_]+\]\??/.test(relativeFromPagesDir);
+}
+
+export function toRoutePattern(relativeFromPagesDir: string): string {
+  const noExt = stripHtSuffix(toPosix(relativeFromPagesDir));
+
+  const withoutGroups = noExt.replace(ROUTE_GROUP_RE, '$1');
+  const withoutIndex = withoutGroups.replace(/\/index$/i, '').replace(/^index$/i, '');
+
+  const raw = withoutIndex
+    .replace(OPTIONAL_CATCH_ALL_SEGMENT_RE, '*?:$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 {
+  const result = pattern
+    .replace(/\*\?:([A-Za-z0-9_]+)/g, (_, key) => {
+      const value = params[key];
+      if (value == null || value === '') {
+        return '';
+      }
+
+      return String(value)
+        .split('/')
+        .map((part) => encodeURIComponent(part))
+        .join('/');
+    })
+    .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]);
+    });
+
+  return normalizeRoutePath(result || '/');
+}
+
+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; i < a.length; i++) {
+    const patternSeg = a[i];
+    const urlSeg = b[i];
+
+    if (patternSeg.startsWith('*?:')) {
+      params[patternSeg.slice(3)] =
+        i < b.length ? b.slice(i).map(safeDecodeURIComponent).join('/') : '';
+      return params;
+    }
+
+    if (patternSeg.startsWith('*:')) {
+      const rest = b.slice(i);
+      if (rest.length === 0) return null;
+
+      params[patternSeg.slice(2)] = rest.map(safeDecodeURIComponent).join('/');
+      return params;
+    }
+
+    if (!urlSeg) return null;
+
+    if (patternSeg.startsWith(':')) {
+      params[patternSeg.slice(1)] = safeDecodeURIComponent(urlSeg);
+      continue;
+    }
+
+    if (patternSeg !== urlSeg) 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 aOptionalCatchAll = aa.startsWith('*?:');
+    const bOptionalCatchAll = bb.startsWith('*?:');
+    if (aOptionalCatchAll !== bOptionalCatchAll) {
+      return aOptionalCatchAll ? 1 : -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;
+    }
+  }
+
+  // More specific / longer routes first when otherwise equal
+  return bSegs.length - aSegs.length;
+}

package/src/types.ts

@@ -0,0 +1,57 @@
+import type { Plugin as RollupPlugin } from 'rollup';
+
+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[]>;
+  dynamic?: boolean;
+  prerender?: boolean;
+}
+
+export interface HtPagesPluginOptions {
+  root?: string;
+  include?: string | string[];
+  exclude?: string | string[];
+  pagesDir?: string;
+  renderConcurrency?: number;
+  renderBatchSize?: number;
+  cleanUrls?: boolean;
+  ssrPlugins?: RollupPlugin[];
+  mapOutputPath?: (page: HtPageInfo) => string;
+  debug?: boolean;
+  site?: string;
+  rss?: {
+    site: string;
+    title?: string;
+    description?: string;
+    routePrefix?: 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,16 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  target: 'node18',
+  splitting: false,
+  external: [
+    'vite',
+    'fast-glob',
+    'p-limit'
+  ],
+});