next-single-file 1.0.0 → 1.0.2

package/README.md

@@ -1,39 +1,50 @@
-# Next.js Single HTML CLI 🚀
+# next-single-file
 
-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
+[![npm version](https://img.shields.io/npm/v/next-single-file?color=black)](https://www.npmjs.com/package/next-single-file)
+[![npm downloads](https://img.shields.io/npm/dm/next-single-file?color=black)](https://www.npmjs.com/package/next-single-file)
+[![Next.js](https://img.shields.io/badge/Next.js-16-black?logo=next.js)](https://nextjs.org)
+[![Bun](https://img.shields.io/badge/runtime-bun-black?logo=bun)](https://bun.sh)
 
-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.
+A CLI tool that transforms a Next.js static export into a **single, self-contained HTML file** with hash-based routing. Regex-based, zero runtime dependencies.
 
-### 🏗 Architecture
+## How it Works
+
+The tool parses your `out/` directory, extracts all routes, and bundles everything into one file. All assets (JS, CSS, fonts, images) are inlined as base64 data URIs, and a hash-based router is injected for client-side navigation.
 
 ```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]
+    B -->|Parser| C[Asset Map & Routes]
+    C -->|Inliner| D[Data URIs & 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]
+    F[Hash Router] -->|Injected| E
+    E -->|Browser| G[Hash Navigation]
 ```
 
-## 🛠 Features
+## Features
+
+- **Self-Contained** — Zero external dependencies. Fonts, images, and scripts are all inlined.
+- **Hash Routing** — Automatically converts path navigation to `#/hash` navigation.
+- **Next.js Compatible** — Supports Geist fonts, Turbopack, and modern Next.js features.
+- **Robust Encoding** — Uses Base64 for the internal route map to prevent minification issues.
+- **Browser Shims** — Polyfills `document.currentScript` and other APIs Next.js expects.
 
-- **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.
+## Installation
+
+```bash
+bunx next-single-file --input out --output dist/index.html
+```
 
-## 🚀 Usage
+Or with npm (requires Bun to be installed):
+
+```bash
+npx next-single-file --input out --output dist/index.html
+```
+
+## Usage
+
+### 1. Configure Next.js for Static Export
 
-### 1. Generate Static Export
 Ensure your `next.config.js` has `output: 'export'`:
 
 ```javascript
@@ -41,35 +52,66 @@ Ensure your `next.config.js` has `output: 'export'`:
 const nextConfig = {
   output: 'export',
 };
+
 module.exports = nextConfig;
 ```
 
-Then build:
+> [!WARNING]  
+> **Purely Client-Side Runtime**  
+> This tool generates a standalone bundle with no backend. 
+> - **Server Logic:** Features like Server Actions, `cookies()`, and Middleware are not supported.
+> - **Dynamic Routes:** You must use `generateStaticParams` for any dynamic paths (e.g., `[id].tsx`) to ensure they are pre-rendered into the `out/` directory before bundling.
+> - **RSC:** React Server Components are supported only insofar as they can be statically rendered to HTML at build time.
+
+### 2. Build Your Next.js App
+
 ```bash
-npm run build
-# or
+# Any pkg manager is fine
 bun run build
 ```
 
-### 2. Run the Inliner
+### 3. Generate Single HTML File
+
 ```bash
-# you need bun installed (can be run by npm tho)
+# npx works too, you need bun installed on your system though
 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
+## Use Cases
+
+| Use Case | Description |
+|----------|-------------|
+| **Portable Demos** | Send a fully functional web app as a single email attachment |
+| **Offline Documentation** | Create interactive docs that work without internet |
+| **Embedded UIs** | Embed Next.js interfaces into desktop apps or dashboards |
+| **Simple Hosting** | Host multi-page apps on GitHub Gists or basic file servers |
+
+## Benchmark
+
+Performance on the included test Next.js app (averaged over 3 runs):
+
+| Metric | Value |
+|--------|-------|
+| **Duration** | ~392 ms |
+| **Output Size** | ~13.9 MB |
+| **Memory Usage** | ~77 MB |
 
-- **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.
+Run your own benchmark:
 
-## 🧪 Development
+```bash
+bun run benchmark
+```
+
+> Results may vary based on your app size and system. The test app includes 4 routes with images, fonts, and interactivity.
+
+## Development
 
-To run the tests:
 ```bash
+bun install
 bun test
+bun run build
 ```
+
+## License
+
+MIT

package/dist/cli.js

@@ -2,8 +2,8 @@
 // @bun
 
 // src/parser.ts
-import { readdir, readFile } from "node:fs/promises";
-import { join, relative, extname } from "node:path";
+import { readdir, readFile } from "fs/promises";
+import { join, relative, extname } from "path";
 async function walk(dir) {
   const files = [];
   const entries = await readdir(dir, { withFileTypes: true });
@@ -412,14 +412,14 @@ function extractMeta(html) {
 function escapeScriptTag(js) {
   return js.replace(/<\/script>/gi, "<\\/script>");
 }
+function minifyHtml(html) {
+  return html.replace(/<!--[\s\S]*?-->/g, "").replace(/>\s+</g, "><").replace(/\s{2,}/g, " ").trim();
+}
 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);
@@ -445,7 +445,7 @@ function bundleToSingleHtml(inlined, routerShim) {
       };
     }
   `;
-  return `<!DOCTYPE html><!--${inlined.buildId}-->
+  const finalHtml = `<!DOCTYPE html><!--${inlined.buildId}-->
 <html${htmlAttrs}>
 <head>
 <meta charset="utf-8">
@@ -473,6 +473,7 @@ ${escapeScriptTag(routerShim)}
 </script>
 </body>
 </html>`;
+  return minifyHtml(finalHtml);
 }
 
 // index.ts
@@ -511,3 +512,5 @@ 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`);
+console.log("Star us: https://github.com/simples-tools/next-single-file");
+console.log("Report bugs: https://github.com/simples-tools/next-single-file/issues");

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "next-single-file",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Convert Next.js static export to a single HTML file with hash routing",
   "bin": {
-    "next-single-file": "./dist/cli.js"
+    "next-single-file": "dist/cli.js"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simples-tools/next-single-file.git"
+  },
+  "author": "@brrock <github.com/brrock>",
   "files": [
     "dist/cli.js"
   ],
   "scripts": {
-    "build": "bun build ./index.ts --target node --outfile ./dist/cli.js && chmod +x ./dist/cli.js",
+    "build": "bun build ./index.ts --target bun --outfile ./dist/cli.js && chmod +x ./dist/cli.js",
     "test": "bun test",
+    "benchmark": "bun run src/benchmark.ts",
     "convert": "bun run ./index.ts"
   },
   "type": "module",