Skip to content

README.md

Latest commit

 

History

History
129 lines (91 loc) · 3.9 KB

README.md

File metadata and controls

129 lines (91 loc) · 3.9 KB

next-single-file

npm version npm downloads Next.js Bun

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.

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.

graph TD
    A[Next.js App] -->|next build| B[out/ Directory]
    B -->|Parser| C[Asset Map & Routes]
    C -->|Inliner| D[Data URIs & Bundles]
    D -->|Bundler| E[Single index.html]
    F[Hash Router] -->|Injected| E
    E -->|Browser| G[Hash Navigation]
Loading

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.

Installation

bunx next-single-file --input out --output dist/index.html

Or with npm (requires Bun to be installed):

npx next-single-file --input out --output dist/index.html

Usage

1. Configure Next.js for Static Export

Ensure your next.config.js has output: 'export':

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
};

module.exports = nextConfig;

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 if they can be statically rendered to HTML at build time.

2. Build Your Next.js App

# Any pkg manager is fine
bun run build

3. Generate Single HTML File

# npx works too, you need bun installed on your system though
bunx next-single-file --input out --output dist/index.html

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

Run your own benchmark:

bun run benchmark

Results may vary based on your app size and system. The test app includes 4 routes with images, fonts, and interactivity.

Telemetry

Anonymized telemetry is collected to help improve the tool. No IP addresses are tracked. All we collect is time taken and RAM used.

To disable telemetry:

NEXT_SINGLE_FILE_NO_TELEMETRY=1 bunx next-single-file --input out

Telemetry is sent by default. Set the above env var to opt out.

Development

bun install
bun test
bun run build

License

MIT