next-single-file 1.0.0

package/README.md

@@ -0,0 +1,75 @@
+# Next.js Single HTML CLI 🚀
+
+A powerful CLI tool that transforms a Next.js static export into a **completely self-contained, single HTML file** with hash-based routing. Regex based, zero deps.
+## 📖 How it Works
+
+The tool crawls your `out/` directory, extracts all routes, and bundles them into a single file. It inlines all assets (JS, CSS, Fonts, Images) as Data URIs (base64) and injects a robust hash-based router.
+
+### 🏗 Architecture
+
+```mermaid
+graph TD
+    A[Next.js App] -->|next build| B[out/ Directory]
+    B -->|Parser| C[Asset Map \u0026 Routes]
+    C -->|Inliner| D[Data URIs \u0026 CSS/JS Bundles]
+    D -->|Bundler| E[Single index.html]
+    F[Hash Router Shim] -->|Injected| E
+    
+    subgraph "Single HTML File"
+    E
+    end
+    
+    E -->|Browser| G[Hash-based Navigation]
+    G -->|#/about| H[DOM Swap via ROUTE_MAP]
+```
+
+## 🛠 Features
+
+- **Self-Contained**: Zero external dependencies. Fonts, images, and scripts are all inlined.
+- **Hash Routing**: Automatically converts path navigation to `#/hash` navigation.
+- **Next.js Compatibility**: Supports latest Next.js features like Geist fonts and Turbopack.
+- **Robust Escaping**: Uses Base64 encoding for the internal route map to prevent minified JS syntax errors.
+- **Shims**: Automatically shims `document.currentScript` and other browser APIs that Next.js expects.
+
+## 🚀 Usage
+
+### 1. Generate Static Export
+Ensure your `next.config.js` has `output: 'export'`:
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  output: 'export',
+};
+module.exports = nextConfig;
+```
+
+Then build:
+```bash
+npm run build
+# or
+bun run build
+```
+
+### 2. Run the Inliner
+```bash
+# you need bun installed (can be run by npm tho)
+bunx next-single-file --input out --output dist/index.html
+# or npm, needs bun installed
+npx next-single-file --input out --output dist/index.html
+
+```
+
+## 🎯 Use Cases
+
+- **Portable Demos**: Send a fully functional web app as a single email attachment.
+- **Offline Documentation**: Create rich, interactive docs that work without an internet connection.
+- **Embedded UIs**: Embed a Next.js interface into desktop applications or hardware dashboards.
+- **Simple Hosting**: Host a multi-page app on GitHub Gists or any basic file server.
+
+## 🧪 Development
+
+To run the tests:
+```bash
+bun test
+```

package/dist/cli.js

@@ -0,0 +1,513 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/parser.ts
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, extname } from "node:path";
+async function walk(dir) {
+  const files = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walk(fullPath));
+    } else {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+function htmlPathToRoute(htmlPath, baseDir) {
+  const relPath = relative(baseDir, htmlPath);
+  const route = relPath.replace(/\.html$/, "").replace(/\\/g, "/").replace(/\/index$/, "").replace(/^index$/, "/");
+  return route.startsWith("/") ? route : "/" + route;
+}
+async function findBuildId(outDir) {
+  try {
+    const staticDir = join(outDir, "_next", "static");
+    const entries = await readdir(staticDir, { withFileTypes: true });
+    const buildDir = entries.find((e) => e.isDirectory() && !e.name.startsWith(".") && e.name !== "chunks" && e.name !== "media");
+    return buildDir?.name || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+async function parseNextOutput(outDir) {
+  const buildId = await findBuildId(outDir);
+  const allFiles = await walk(outDir);
+  const routes = [];
+  const cssFiles = new Map;
+  const jsFiles = new Map;
+  const fontFiles = new Map;
+  const imageFiles = new Map;
+  for (const file of allFiles) {
+    const relPath = "/" + relative(outDir, file).replace(/\\/g, "/");
+    const ext = extname(file).toLowerCase();
+    if (ext === ".html") {
+      const htmlContent = await readFile(file, "utf-8");
+      routes.push({
+        path: htmlPathToRoute(file, outDir),
+        htmlFile: file,
+        htmlContent
+      });
+    } else if (ext === ".css") {
+      cssFiles.set(relPath, await readFile(file, "utf-8"));
+    } else if (ext === ".js") {
+      jsFiles.set(relPath, await readFile(file, "utf-8"));
+    } else if ([".woff2", ".woff", ".ttf", ".otf"].includes(ext)) {
+      const buffer = await readFile(file);
+      fontFiles.set(relPath, buffer.buffer);
+    } else if ([".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".avif"].includes(ext)) {
+      const buffer = await readFile(file);
+      imageFiles.set(relPath, buffer.buffer);
+    }
+  }
+  return {
+    buildId,
+    routes,
+    cssFiles,
+    jsFiles,
+    fontFiles,
+    imageFiles
+  };
+}
+
+// src/inliner.ts
+function extractHeadContent(html) {
+  const match = html.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
+  return match && match[1] ? match[1] : "";
+}
+function extractBodyContent(html) {
+  const match = html.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
+  return match && match[1] ? match[1] : "";
+}
+function toDataUri(data, path) {
+  const ext = path.split(".").pop()?.toLowerCase();
+  let mime = "application/octet-stream";
+  if (ext === "svg")
+    mime = "image/svg+xml";
+  else if (ext === "png")
+    mime = "image/png";
+  else if (ext === "jpg" || ext === "jpeg")
+    mime = "image/jpeg";
+  else if (ext === "webp")
+    mime = "image/webp";
+  else if (ext === "ico")
+    mime = "image/x-icon";
+  else if (ext === "woff2")
+    mime = "font/woff2";
+  else if (ext === "woff")
+    mime = "font/woff";
+  else if (ext === "ttf")
+    mime = "font/ttf";
+  else if (ext === "otf")
+    mime = "font/otf";
+  else if (ext === "js")
+    mime = "application/javascript";
+  else if (ext === "css")
+    mime = "text/css";
+  const base64 = typeof data === "string" ? Buffer.from(data, "utf-8").toString("base64") : Buffer.from(data).toString("base64");
+  return `data:${mime};base64,${base64}`;
+}
+function extractStyles(html) {
+  const styleRegex = /<style[^>]*>([\s\S]*?)<\/style>/gi;
+  let styles = "";
+  let match;
+  while ((match = styleRegex.exec(html)) !== null) {
+    styles += match[1] + `
+`;
+  }
+  return styles;
+}
+async function inlineAssets(parsed) {
+  const assetMap = new Map;
+  for (const [path, buffer] of parsed.fontFiles) {
+    assetMap.set(path, toDataUri(buffer, path));
+  }
+  for (const [path, buffer] of parsed.imageFiles) {
+    assetMap.set(path, toDataUri(buffer, path));
+  }
+  for (const [path, content] of parsed.cssFiles) {
+    assetMap.set(path, toDataUri(content, path));
+  }
+  for (const [path, content] of parsed.jsFiles) {
+    assetMap.set(path, toDataUri(content, path));
+  }
+  const sortedPaths = Array.from(assetMap.keys()).sort((a, b) => b.length - a.length);
+  function inlineEverything(content) {
+    let result = content;
+    for (const path of sortedPaths) {
+      const dataUri = assetMap.get(path);
+      const fileName = path.split("/").pop();
+      const escapedPath = path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const pathPattern = new RegExp(`(?:\\\\?["'\\(\\s,])(?:https?:\\/\\/[^/]+)?${escapedPath}(?:\\?[^\\\\"'\\)\\s,]+)?(?:\\\\?["'\\)\\s,])`, "g");
+      result = result.replace(pathPattern, (match) => {
+        const prefixMatch = match.match(/^(\\?["'\\(\\s,])/);
+        const suffixMatch = match.match(/(\\?["'\\)\\s,])$/);
+        const prefix = prefixMatch ? prefixMatch[0] : "";
+        const suffix = suffixMatch ? suffixMatch[0] : "";
+        return `${prefix}${dataUri}${suffix}`;
+      });
+      if (path.startsWith("/")) {
+        const noSlashPath = path.slice(1).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const noSlashPattern = new RegExp(`(?:\\\\?["'\\(\\s,])(?:https?:\\/\\/[^/]+)?${noSlashPath}(?:\\?[^\\\\"'\\)\\s,]+)?(?:\\\\?["'\\)\\s,])`, "g");
+        result = result.replace(noSlashPattern, (match) => {
+          const prefixMatch = match.match(/^(\\?["'\\(\\s,])/);
+          const suffixMatch = match.match(/(\\?["'\\)\\s,])$/);
+          const prefix = prefixMatch ? prefixMatch[0] : "";
+          const suffix = suffixMatch ? suffixMatch[0] : "";
+          return `${prefix}${dataUri}${suffix}`;
+        });
+      }
+      if (fileName) {
+        const escapedFileName = fileName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const relPattern = new RegExp(`(?:\\\\?["'\\(\\s])(?:\\.\\.?\\/|\\/_next\\/static\\/)?(?:media|chunks|css)\\/${escapedFileName}(?:\\?[^\\\\"'\\)\\s]+)?(?:\\\\?["'\\)\\s])`, "g");
+        result = result.replace(relPattern, (match) => {
+          const prefixMatch = match.match(/^(\\?["'\\(\\s])/);
+          const suffixMatch = match.match(/(\\?["'\\)\\s])$/);
+          const prefix = prefixMatch ? prefixMatch[0] : "";
+          const suffix = suffixMatch ? suffixMatch[0] : "";
+          return `${prefix}${dataUri}${suffix}`;
+        });
+      }
+    }
+    return result;
+  }
+  const processedCssFiles = new Map;
+  for (const [path, content] of parsed.cssFiles) {
+    processedCssFiles.set(path, inlineEverything(content));
+  }
+  const processedJsFiles = new Map;
+  for (const [path, content] of parsed.jsFiles) {
+    processedJsFiles.set(path, inlineEverything(content));
+  }
+  let inlinedCss = Array.from(processedCssFiles.values()).join(`
+`);
+  const inlinedJs = Array.from(processedJsFiles.values()).join(`
+`);
+  const routes = parsed.routes.map((route) => {
+    let inlinedHtml = inlineEverything(route.htmlContent);
+    const routeStyles = extractStyles(inlinedHtml);
+    inlinedCss += `
+` + routeStyles;
+    inlinedHtml = inlinedHtml.replace(/<link[^>]+rel=["']preload["'][^>]*>/gi, "");
+    return {
+      path: route.path,
+      headContent: extractHeadContent(inlinedHtml),
+      bodyContent: extractBodyContent(inlinedHtml),
+      htmlContent: inlinedHtml
+    };
+  });
+  return {
+    buildId: parsed.buildId,
+    routes,
+    inlinedCss,
+    inlinedJs,
+    allInlinedFiles: assetMap
+  };
+}
+
+// src/router.ts
+function generateRouterShim(routes) {
+  const routeMap = {};
+  for (const route of routes) {
+    const cleanPath = route.path === "/" ? "/" : route.path.replace(/\/$/, "");
+    routeMap[cleanPath] = {
+      head: route.headContent,
+      body: route.bodyContent
+    };
+  }
+  const routeMapJson = JSON.stringify(routeMap);
+  const routeMapBase64 = Buffer.from(routeMapJson).toString("base64");
+  return `
+(function() {
+  const ROUTE_MAP_BASE64 = "${routeMapBase64}";
+  let ROUTE_MAP = {};
+  
+  function b64DecodeUnicode(str) {
+    return decodeURIComponent(atob(str).split('').map(function(c) {
+      return '%' + ('00' + c.charCodeAt(0).toString(16)).slice(-2);
+    }).join(''));
+  }
+
+  try {
+    ROUTE_MAP = JSON.parse(b64DecodeUnicode(ROUTE_MAP_BASE64));
+  } catch (e) {
+    console.error("Failed to parse ROUTE_MAP", e);
+    try {
+      ROUTE_MAP = JSON.parse(window.atob(ROUTE_MAP_BASE64));
+    } catch (e2) {
+      console.error("Fallback parsing also failed", e2);
+    }
+  }
+
+  let currentRoute = '/';
+  let isInitialized = false;
+
+  // Intercept Next.js chunk loading to prevent network requests
+  if (typeof window !== 'undefined') {
+    window.__NEXT_DATA__ = window.__NEXT_DATA__ || { props: { pageProps: {} }, page: "/", query: {}, buildId: "single-file" };
+    // Disable automatic prefetching
+    window.__NEXT_P = window.__NEXT_P || [];
+  }
+
+  function getHashPath() {
+    let hash = window.location.hash.slice(1);
+    if (!hash || hash === '') hash = '/';
+    if (!hash.startsWith('/')) hash = '/' + hash;
+    return hash;
+  }
+
+  function normalizePath(path) {
+    if (!path) return '/';
+    if (path === '/') return '/';
+    return path.endsWith('/') ? path.slice(0, -1) : path;
+  }
+
+  function renderRoute(path, skipIfSame) {
+    path = normalizePath(path);
+    if (skipIfSame && path === currentRoute) return;
+    
+    const route = ROUTE_MAP[path];
+    
+    if (!route || !route.body) {
+      console.warn('Route not found or empty:', path, '- available routes:', Object.keys(ROUTE_MAP));
+      const notFoundRoute = ROUTE_MAP['/404'] || ROUTE_MAP['/_not-found'];
+      if (notFoundRoute && notFoundRoute.body) {
+        const rootEl = document.getElementById('__next') || document.body;
+        rootEl.innerHTML = notFoundRoute.body;
+      }
+      return;
+    }
+
+    // Update title
+    if (route.head) {
+      const titleMatch = route.head.match(/<title[^>]*>([\\s\\S]*?)<\\/title>/i);
+      if (titleMatch && titleMatch[1]) {
+        document.title = titleMatch[1];
+      }
+    }
+
+    const rootEl = document.getElementById('__next') || document.body;
+    rootEl.innerHTML = route.body;
+    currentRoute = path;
+    
+    // Re-execute scripts
+    const scripts = rootEl.querySelectorAll('script');
+    scripts.forEach(oldScript => {
+      const newScript = document.createElement('script');
+      Array.from(oldScript.attributes).forEach(attr => newScript.setAttribute(attr.name, attr.value));
+      if (oldScript.src) {
+        newScript.src = oldScript.src;
+      } else {
+        newScript.textContent = oldScript.textContent;
+      }
+      oldScript.parentNode.replaceChild(newScript, oldScript);
+    });
+
+    window.scrollTo(0, 0);
+    document.dispatchEvent(new CustomEvent('routeChange', { detail: { path } }));
+  }
+
+  // Intercept pushState/replaceState
+  const origPush = history.pushState.bind(history);
+  const origReplace = history.replaceState.bind(history);
+
+  history.pushState = function(state, title, url) {
+    if (url && typeof url === 'string' && !url.startsWith('#') && !url.startsWith('http')) {
+      window.location.hash = url;
+      return;
+    }
+    return origPush(state, title, url);
+  };
+
+  history.replaceState = function(state, title, url) {
+    if (url && typeof url === 'string' && !url.startsWith('#') && !url.startsWith('http')) {
+      window.location.hash = url;
+      return;
+    }
+    return origReplace(state, title, url);
+  };
+
+  document.addEventListener('click', (e) => {
+    let target = e.target;
+    while (target && target !== document) {
+      if (target.tagName === 'A') break;
+      target = target.parentElement;
+    }
+    
+    if (target && target.tagName === 'A') {
+      const href = target.getAttribute('href');
+      if (href && href.startsWith('/') && !href.startsWith('//')) {
+        const isExternal = target.target === '_blank' || target.hasAttribute('download');
+        if (!isExternal) {
+          e.preventDefault();
+          window.location.hash = href;
+        }
+      }
+    }
+  }, true);
+
+  window.addEventListener('hashchange', () => {
+    const path = getHashPath();
+    renderRoute(path, false);
+  });
+
+  function init() {
+    if (isInitialized) return;
+    isInitialized = true;
+    const initialPath = getHashPath();
+    if (initialPath !== '/') {
+      renderRoute(initialPath, false);
+    }
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    setTimeout(init, 0);
+  }
+
+  window.__NEXT_SINGLE_FILE_ROUTER__ = {
+    navigate: (path) => {
+      window.location.hash = path;
+    },
+    getCurrentRoute: () => currentRoute,
+    getRouteMap: () => ROUTE_MAP,
+    renderRoute: renderRoute,
+  };
+})();
+`;
+}
+
+// src/bundler.ts
+function extractHtmlAttrs(html) {
+  const htmlMatch = html.match(/<html([^>]*)>/i);
+  return htmlMatch && htmlMatch[1] ? htmlMatch[1] : ' lang="en"';
+}
+function extractBodyAttrs(html) {
+  const bodyMatch = html.match(/<body([^>]*)>/i);
+  return bodyMatch && bodyMatch[1] ? bodyMatch[1] : "";
+}
+function extractTitle(html) {
+  const titleMatch = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  return titleMatch && titleMatch[1] ? titleMatch[1] : "App";
+}
+function extractMeta(html) {
+  const headMatch = html.match(/<head[^>]*>([\s\S]*?)<\/head>/i);
+  if (!headMatch)
+    return "";
+  const head = headMatch[1] || "";
+  const metaTags = [];
+  const metaRegex = /<meta[^>]*>/gi;
+  let match;
+  while ((match = metaRegex.exec(head)) !== null) {
+    if (match[0].includes('name="viewport"'))
+      continue;
+    metaTags.push(match[0]);
+  }
+  return metaTags.join(`
+`);
+}
+function escapeScriptTag(js) {
+  return js.replace(/<\/script>/gi, "<\\/script>");
+}
+function bundleToSingleHtml(inlined, routerShim) {
+  const indexRoute = inlined.routes.find((r) => r.path === "/");
+  if (!indexRoute) {
+    throw new Error("No index route found");
+  }
+  const anyRoute = inlined.routes[0];
+  if (!anyRoute)
+    throw new Error("No routes found");
+  const htmlAttrs = extractHtmlAttrs(indexRoute.htmlContent);
+  const bodyAttrs = extractBodyAttrs(indexRoute.htmlContent);
+  const title = extractTitle(indexRoute.headContent);
+  const meta = extractMeta(indexRoute.headContent);
+  const runtimeShims = `
+    // SHIM: Next.js/Turbopack runtime fix
+    if (typeof document !== 'undefined') {
+      if (!document.currentScript) {
+        const scripts = document.getElementsByTagName('script');
+        Object.defineProperty(document, 'currentScript', {
+          get: function() { return scripts[scripts.length - 1] || null; },
+          configurable: true
+        });
+      }
+      
+      const origGetAttr = HTMLElement.prototype.getAttribute;
+      HTMLElement.prototype.getAttribute = function(name) {
+        const val = origGetAttr.apply(this, arguments);
+        if (name === 'src' && val === null && this.tagName === 'SCRIPT') {
+          return ''; 
+        }
+        return val;
+      };
+    }
+  `;
+  return `<!DOCTYPE html><!--${inlined.buildId}-->
+<html${htmlAttrs}>
+<head>
+<meta charset="utf-8">
+<script>${runtimeShims}</script>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+${meta}
+<title>${title}</title>
+<style>
+${inlined.inlinedCss}
+</style>
+<script>
+/* NEXT_JS_CHUNKS_START */
+${escapeScriptTag(inlined.inlinedJs)}
+/* NEXT_JS_CHUNKS_END */
+</script>
+</head>
+<body${bodyAttrs}>
+<div id="__next">
+${indexRoute.bodyContent}
+</div>
+<script>
+/* ROUTER_SHIM_START */
+${escapeScriptTag(routerShim)}
+/* ROUTER_SHIM_END */
+</script>
+</body>
+</html>`;
+}
+
+// index.ts
+var {$ } = globalThis.Bun;
+function parseArgs() {
+  const args = process.argv.slice(2);
+  let inputDir = "out";
+  let outputFile = "dist/index.html";
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--input" || arg === "-i") {
+      inputDir = args[++i] || inputDir;
+    } else if (arg === "--output" || arg === "-o") {
+      outputFile = args[++i] || outputFile;
+    } else if (arg && !arg.startsWith("-")) {
+      if (inputDir === "out") {
+        inputDir = arg;
+      } else {
+        outputFile = arg;
+      }
+    }
+  }
+  return { inputDir, outputFile };
+}
+var { inputDir, outputFile } = parseArgs();
+console.log(`\uD83D\uDCD6 Parsing Next.js output from: ${inputDir}`);
+var parsed = await parseNextOutput(inputDir);
+console.log(`\uD83D\uDCE6 Found ${parsed.routes.length} routes:`, parsed.routes.map((r) => r.path));
+console.log(`\uD83D\uDD27 Inlining assets...`);
+var inlined = await inlineAssets(parsed);
+console.log(`\uD83D\uDD00 Generating hash router...`);
+var routerShim = generateRouterShim(inlined.routes);
+console.log(`\uD83D\uDCDD Bundling to single HTML...`);
+var html = bundleToSingleHtml(inlined, routerShim);
+await $`mkdir -p ${outputFile.split("/").slice(0, -1).join("/") || "."}`.quiet();
+await Bun.write(outputFile, html);
+console.log(`\u2705 Done! Output: ${outputFile}`);
+console.log(`   Size: ${(html.length / 1024).toFixed(1)} KB`);

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "next-single-file",
+  "version": "1.0.0",
+  "description": "Convert Next.js static export to a single HTML file with hash routing",
+  "bin": {
+    "next-single-file": "./dist/cli.js"
+  },
+  "files": [
+    "dist/cli.js"
+  ],
+  "scripts": {
+    "build": "bun build ./index.ts --target node --outfile ./dist/cli.js && chmod +x ./dist/cli.js",
+    "test": "bun test",
+    "convert": "bun run ./index.ts"
+  },
+  "type": "module",
+  "workspaces": [
+    "test-next-app"
+  ],
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}