twynejs 1.0.1 → 1.0.3

package/dist/index.d.ts

@@ -30,6 +30,8 @@ export interface PagesPluginOptions {
      * URLs). The page with id `"index"` is always emitted as the top-level
      * `index.html`, never `index/index.html`.
      *
+     * Ignored when `singleFile` is enabled.
+     *
      * @default false
      */
     prettyUrls?: boolean;
@@ -60,6 +62,9 @@ export interface PagesPluginOptions {
      * Wrap/replace the emitted HTML shell entirely. Receives the computed
      * script/style tags and page metadata; must return a full HTML document.
      * Falls back to a minimal built-in template.
+     *
+     * Not used when `singleFile` is enabled — the single-file shell has its
+     * own hash-router bootstrap and is built independently of `template`.
      */
     template?: (ctx: PageRenderContext) => string;
     /** Minify emitted HTML with html-minifier-terser. @default false */
@@ -134,6 +139,9 @@ export interface PagesPluginOptions {
      * Put each compiled Markdown page into its own dynamically loaded chunk
      * instead of embedding all Markdown HTML into the main bundle.
      *
+     * Forced back to `false` when `singleFile` is enabled — a split chunk
+     * would defeat the point of a single-file export.
+     *
      * @default false
      */
     splitMarkdown?: boolean;
@@ -157,6 +165,40 @@ export interface PagesPluginOptions {
      * @default "twynejs/jsx-runtime"
      */
     jsxRuntimePath?: string;
+    /**
+     * Emit the whole site as a single `index.html` file with client-side,
+     * hash-based routing (`#/guide/install`) instead of one HTML file per
+     * page. Everything needed to render every "component"/"markdown" page —
+     * JS and CSS — is inlined into that one file, so the result can be
+     * opened directly via `file://`, embedded, or dropped onto any static
+     * host with no server-side rewrites.
+     *
+     * What this implies automatically, so you normally don't need to set
+     * them yourself:
+     *
+     * - Rollup output is forced to `inlineDynamicImports: true` (like
+     *   `singleBundle`), so every page ends up in one JS chunk.
+     * - `splitMarkdown` is ignored (forced off) and all build data is
+     *   inlined regardless of size — there is nowhere else to put it.
+     *
+     * Limitations:
+     *
+     * - Only `"component"` and `"markdown"` pages participate in the
+     *   router. Liquid (`.html`) and EJS (`.ejs`) pages are build-time
+     *   *static* documents and are not compatible with a client-side hash
+     *   router; if any exist, they are skipped with a build warning.
+     * - The shared client `entry` is responsible for reading
+     *   `window[globalVar]` on load, calling `pages[id].load()` to mount it,
+     *   and listening for the `window` `"pagechange"` `CustomEvent`
+     *   (`event.detail.id`) to re-render when the hash changes, since the
+     *   plugin only owns the HTML shell and the routing bootstrap, not your
+     *   app's rendering logic.
+     * - `template`/`prettyUrls`/per-page output file naming are not used;
+     *   the output is always a single `index.html`.
+     *
+     * @default false
+     */
+    singleFile?: boolean;
 }
 export interface PageRenderContext {
     id: string;

package/dist/index.js

@@ -48,6 +48,17 @@ function escapeBareAngles(html) {
         return `&lt;${inner.replace(/</g, "&lt;")}&gt;`;
     });
 }
+/**
+ * Escape `</script` inside a string that will be embedded verbatim into an
+ * inline `<script>` tag. The HTML tokenizer ends a `<script>` element the
+ * moment it sees the literal text `</script`, regardless of whether that
+ * text sits inside a JS string/comment — without this, bundled code that
+ * happens to contain that substring (e.g. inside a template literal)
+ * would truncate the page.
+ */
+function escapeScriptClose(code) {
+    return code.replace(/<\/script/gi, "<\\/script");
+}
 let resolvedStyles = new Map();
 const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"];
 export function pagesPlugin(options = {}) {
@@ -61,9 +72,12 @@ export function pagesPlugin(options = {}) {
         "/__devtools-oxc/",
         ...(options.ignoredPathnames ?? []),
     ].filter((prefix, index, prefixes) => prefixes.indexOf(prefix) === index);
-    const splitMarkdown = options.splitMarkdown ?? false;
     const verbose = options.verbose ?? false;
     const singleBundle = options.singleBundle ?? false;
+    // Single-file export needs everything in one JS chunk and everything
+    // inlined, so it forces off `splitMarkdown` regardless of what was set.
+    const singleFile = options.singleFile ?? false;
+    const splitMarkdown = (options.splitMarkdown ?? false) && !singleFile;
     const removeConsole = options.removeConsole ?? false;
     const relativePath = options.relativePaths ?? false;
     const addRawMarkdown = options.addRawMarkdown ?? false;
@@ -392,6 +406,10 @@ export function pagesPlugin(options = {}) {
             const styles = page.styles
                 .map((style) => styleImports.get(style))
                 .join(", ");
+            // Exposed to the client so an app (in particular a `singleFile`
+            // hash-router shell) can update `document.title` itself when the
+            // active page changes, without a full page reload.
+            const titleField = `title: ${JSON.stringify(getTitle(page.id))},`;
             /* Liquid/EJS template pages are fully static (rendered at build
              * time) — they are served/emitted as-is and do not need a
              * client-side entry in the pages map (which would bloat the
@@ -404,6 +422,7 @@ export function pagesPlugin(options = {}) {
                     return `  ${JSON.stringify(page.id)}: {
     id: ${JSON.stringify(page.id)},
     type: "component",
+    ${titleField}
     load: () => import(${JSON.stringify(page.importPath ?? page.scriptSource)}),
     styles: []
   }`;
@@ -419,6 +438,7 @@ export function pagesPlugin(options = {}) {
                     return `  ${JSON.stringify(page.id)}: {
     id: ${JSON.stringify(page.id)},
     type: "markdown",
+    ${titleField}
     load: () => import(${JSON.stringify(markdownModuleId)}),
     styles: [${styles}]
   }`;
@@ -429,6 +449,7 @@ export function pagesPlugin(options = {}) {
                 return `  ${JSON.stringify(page.id)}: {
     id: ${JSON.stringify(page.id)},
     type: "markdown",
+    ${titleField}
     ${markdownField}
     html: ${JSON.stringify(page.html ?? "")},
     styles: [${styles}]
@@ -437,14 +458,17 @@ export function pagesPlugin(options = {}) {
             // Große Build-Daten (z. B. gerendertes Markdown) nicht inline in
             // den Entry packen, sondern in einen eigenen Chunk auslagern, der
             // erst beim Laden der Seite per import() geholt wird.
+            // In `singleFile` mode there is nowhere else to put a lazily
+            // loaded chunk, so everything is always inlined regardless of size.
             const dataSize = typeof page.buildData === "string" ? page.buildData.length : 1024;
-            const inlineData = dataSize < 8 * 1024;
+            const inlineData = singleFile || dataSize < 8 * 1024;
             const dataField = inlineData
                 ? `data: ${JSON.stringify(page.buildData ?? null)},`
                 : `loadData: () => import(${JSON.stringify(DATA_PREFIX + page.id)}).then((m) => m.default),`;
             return `  ${JSON.stringify(page.id)}: {
     id: ${JSON.stringify(page.id)},
     type: "component",
+    ${titleField}
     load: () => import(${JSON.stringify(page.importPath)}),
     ${dataField}
     styles: [${styles}]
@@ -490,6 +514,10 @@ declare module "virtual:pages" {
   export interface ComponentPage {
     id: string;
     type: "component";
+    /** Resolved via the plugin's \`title\` option. Handy for setting
+     *  \`document.title\` yourself when routing client-side (e.g. in
+     *  \`singleFile\` / hash-router mode). */
+    title: string;
     data?: unknown;
     /** Lazy-loaded build data (large payloads). */
     loadData?: () => Promise<unknown>;
@@ -500,6 +528,7 @@ declare module "virtual:pages" {
   export interface MarkdownPage {
     id: string;
     type: "markdown";
+    title: string;
     markdown?: string;
     html: string;
     styles: string[];
@@ -513,14 +542,20 @@ declare module "virtual:pages" {
   }>;
   }
 
-  export interface LiquidPage {
-    id: string;
-    type: "liquid";
-    html: string;
-    styles: string[];
-  }
-
-  export type PageEntry = ComponentPage | MarkdownPage | LiquidPage;
+  // Note: there is intentionally no exported "LiquidPage" variant here.
+  // Liquid/EJS template pages are rendered fully at build time as
+  // standalone static documents; when one of them also has a sibling
+  // client script (\`page.[tj]s\`), it is exposed through \`virtual:pages\`
+  // as an ordinary ComponentPage (\`type: "component"\`) so the app can
+  // mount it like any other page. Without a sibling script it never
+  // appears in \`pages\` at all. A runtime object shaped like
+  // \`{ type: "liquid", ... }\` is never actually produced, so including
+  // it in this union previously made every \`pages[id]\` access widen to
+  // \`ComponentPage | LiquidPage\` after narrowing out "markdown", even
+  // though \`LiquidPage\` has no \`load\` — causing spurious
+  // "Property 'load' does not exist on type 'LiquidPage'" errors in
+  // consumers under \`tsc -b\`.
+  export type PageEntry = ComponentPage | MarkdownPage;
 
   export const pages: Record<string, PageEntry>;
 }
@@ -580,6 +615,31 @@ ${ctx.content}
 </body>
 </html>
 `;
+    }
+    /**
+     * Bootstrap script for `singleFile` mode: derives the current page id
+     * from `location.hash` (`#/guide/install` → `"guide/install"`, empty →
+     * `rootId`), exposes it on `window[globalVar]` just like the multi-page
+     * template does, and re-derives it on every `hashchange`, dispatching a
+     * `"pagechange"` `CustomEvent` (`event.detail.id`) so the app's entry can
+     * re-render without a full page reload.
+     */
+    function singleFileBootstrapScript(rootId) {
+        return `(function () {
+  var DEFAULT_PAGE = ${JSON.stringify(rootId)};
+  function currentPageId() {
+    var hash = window.location.hash || "";
+    hash = hash.replace(/^#\\/?/, "").replace(/\\/+$/, "");
+    return hash || DEFAULT_PAGE;
+  }
+  window.${globalVar} = currentPageId();
+  window.addEventListener("hashchange", function () {
+    window.${globalVar} = currentPageId();
+    window.dispatchEvent(
+      new CustomEvent("pagechange", { detail: { id: window.${globalVar} } })
+    );
+  });
+})();`;
     }
     return {
         name: "vite-plugin-pages-ssg",
@@ -624,6 +684,7 @@ ${ctx.content}
       export default ${JSON.stringify({
                     id: page.id,
                     type: "markdown",
+                    title: getTitle(page.id),
                     ...(addRawMarkdown ? { markdown: page.markdown ?? "" } : {}),
                     html: page.html ?? "",
                 })};
@@ -686,6 +747,12 @@ ${ctx.content}
             // Serve each page's HTML on its own dev URL (e.g. /guide/installation
             // or /guide/installation.html), mirroring what generateBundle emits
             // for production, so `vite dev` is multi-page too — not just the build.
+            //
+            // Note: `singleFile` only changes the *production build* output.
+            // The dev server keeps serving one URL per page id as usual — the
+            // hash-router bootstrap only exists in the emitted single-file
+            // production HTML — since normal multi-URL dev navigation is more
+            // convenient while developing.
             const entry = "/" +
                 (options.entry ?? "src/main.ts")
                     .replace(/\\/g, "/")
@@ -816,9 +883,9 @@ ${ctx.content}
                 res.end(transformed);
             });
         },
-        // for single bundle
+        // for single bundle / single file
         config() {
-            if (!singleBundle && !removeConsole) {
+            if (!singleBundle && !removeConsole && !singleFile) {
                 return {};
             }
             const esbuild = {};
@@ -829,7 +896,9 @@ ${ctx.content}
                 esbuild.drop = ["console"];
             }
             const build = {};
-            if (singleBundle) {
+            if (singleBundle || singleFile) {
+                // `singleFile` needs exactly one JS chunk to inline into the HTML
+                // shell, same requirement as `singleBundle`.
                 build.rollupOptions = {
                     output: {
                         inlineDynamicImports: true,
@@ -889,6 +958,27 @@ ${ctx.content}
                 return;
             }
             const entryJsChunk = jsChunk;
+            /*
+             * Single-file export: skip the normal per-page HTML emission
+             * entirely — the actual `index.html` is assembled in `writeBundle`
+             * instead (see below), once every other plugin's `generateBundle`
+             * hook (including Vite's own internal dynamic-import / preload
+             * handling, e.g. its `__VITE_PRELOAD__` substitution) has already
+             * run. Reading `entryJsChunk.code` here, in this plugin's own
+             * `generateBundle` (registered with `enforce: "pre"`, so it can run
+             * *before* Vite's internal build plugins), would risk capturing
+             * unfinished code and inlining an unresolved `__VITE_PRELOAD__`
+             * placeholder straight into the page.
+             */
+            if (singleFile) {
+                const skippedPages = pages.filter((page) => page.type === "liquid" || page.type === "ejs");
+                if (skippedPages.length > 0) {
+                    this.warn(`[vite-plugin-pages-ssg] singleFile: skipping ${skippedPages.length} Liquid/EJS page(s) (${skippedPages
+                        .map((page) => page.id)
+                        .join(", ")}) — they are static, build-time-rendered documents and are not compatible with the single-file hash router. Only "component" and "markdown" pages are bundled into index.html.`);
+                }
+                return;
+            }
             for (const page of pages) {
                 const htmlFileName = outputFileName(page.id);
                 const htmlDir = path.dirname(htmlFileName);
@@ -1053,6 +1143,109 @@ ${ctx.content}
                 });
             }
         },
+        /*
+         * Runs strictly after every plugin's `generateBundle` hook has
+         * finished and Rollup has already written the bundle to disk — so by
+         * now Vite's own internal transforms (dynamic-import preload
+         * handling, `__VITE_PRELOAD__` substitution, etc.) are guaranteed to
+         * be fully resolved in `bundle[...].code`. This is what makes it safe
+         * to read the entry chunk's final code and inline it, unlike doing
+         * the same thing inside `generateBundle` (see the comment there).
+         */
+        async writeBundle(outputOptions, bundle) {
+            if (!singleFile) {
+                return;
+            }
+            const entryJsChunk = Object.values(bundle).find((item) => item.type === "chunk" &&
+                item.isEntry &&
+                item.fileName.endsWith(".js"));
+            if (!entryJsChunk || entryJsChunk.type !== "chunk") {
+                this.error("[vite-plugin-pages-ssg] singleFile: could not find the generated entry .js chunk while writing the bundle.");
+                return;
+            }
+            const otherChunkCount = Object.values(bundle).filter((item) => item.type === "chunk" && item !== entryJsChunk).length;
+            if (otherChunkCount > 0) {
+                this.warn(`[vite-plugin-pages-ssg] singleFile: found ${otherChunkCount} extra JS chunk(s) besides the entry chunk that could not be inlined into index.html. They will still be left as separate files, so the build is not a true single file — check for a custom "manualChunks"/"output" config that overrides "inlineDynamicImports".`);
+            }
+            const cssParts = [];
+            const cssFileNames = [];
+            for (const [fileName, item] of Object.entries(bundle)) {
+                if (item.type === "asset" && fileName.toLowerCase().endsWith(".css")) {
+                    const source = item.source;
+                    cssParts.push(typeof source === "string"
+                        ? source
+                        : Buffer.from(source).toString("utf8"));
+                    cssFileNames.push(fileName);
+                }
+            }
+            const cssContent = cssParts.join("\n");
+            const bundledPages = pages.filter((page) => page.type === "component" || page.type === "markdown");
+            const rootId = bundledPages.some((page) => page.id === "index")
+                ? "index"
+                : (bundledPages[0]?.id ?? "index");
+            const title = getTitle(rootId);
+            const head = getHead(rootId);
+            const bootstrapScript = singleFileBootstrapScript(rootId);
+            const inlineJs = escapeScriptClose(entryJsChunk.code);
+            let html = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${escapeHtml(title)}</title>
+  ${cssContent ? `<style>\n${cssContent}\n  </style>` : ""}
+  ${head}
+</head>
+<body>
+  <div id="app"></div>
+
+  <script>
+${bootstrapScript}
+  </script>
+
+  <script type="module">
+${inlineJs}
+  </script>
+</body>
+</html>
+`;
+            if (options.minify) {
+                html = await minify(html, {
+                    collapseWhitespace: true,
+                    removeComments: true,
+                    removeRedundantAttributes: true,
+                    removeEmptyAttributes: true,
+                    useShortDoctype: true,
+                    minifyCSS: true,
+                    minifyJS: true,
+                });
+            }
+            const outDir = path.resolve(config.root, outputOptions.dir ?? config.build.outDir ?? "dist");
+            fs.writeFileSync(path.join(outDir, "index.html"), html, "utf8");
+            // The entry chunk and every CSS asset are now embedded directly in
+            // index.html (already written above) — remove the now-redundant
+            // loose files from disk so only index.html remains.
+            const filesToRemove = [entryJsChunk.fileName, ...cssFileNames];
+            const dirsTouched = new Set();
+            for (const fileName of filesToRemove) {
+                const filePath = path.join(outDir, fileName);
+                if (fs.existsSync(filePath)) {
+                    fs.rmSync(filePath);
+                    dirsTouched.add(path.dirname(filePath));
+                }
+            }
+            // Clean up asset directories (e.g. "assets/") left empty behind.
+            for (const dir of dirsTouched) {
+                if (dir !== outDir &&
+                    fs.existsSync(dir) &&
+                    fs.readdirSync(dir).length === 0) {
+                    fs.rmdirSync(dir);
+                }
+            }
+            if (verbose) {
+                console.log(`[vite-plugin-pages-ssg] Emitted single-file build: index.html (${bundledPages.length} page(s) bundled)`);
+            }
+        },
     };
 }
 function getPageId(url, pages) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twynejs",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "twine A Vite SSG plugin that turns .ts/.tsx pages, Markdown docs and Liquid/EJS templates into a multi-page static build with a virtual:pages module.",
   "type": "module",
   "main": "./dist/index.js",