Bun Standalone HTML

Files (1)

• SKILL.md

SKILL.md (first lines)

# Standalone HTML

> Bundle a single-page app into a single self-contained .html file with no external dependencies

Bun can bundle your entire frontend into a **single `.html` file** with zero external dependencies. JavaScript, TypeScript, JSX, CSS, images, fonts, videos, WASM — everything gets inlined into one file.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build --compile --target=browser ./index.html --outdir=dist
```

The output is a completely self-contained HTML document. No relative paths. No external files. No server required. Just one `.html` file that works anywhere a browser can open it.

## One file. Upload anywhere. It just works.

The output is a single `.html` file you can put anywhere:

* **Upload it to S3** or any static file host — no directory structure to maintain, just one file
* **Double-click it from your desktop** — it opens in the browser and works offline, no localhost server needed
* **Embed it in your webview** — No need to deal with relative files
* **Insert it in an `<iframe>`** — embed interactive content in another page with a single file URL
* **Serve it from anywhere** — any HTTP server, CDN, or file share. One file, zero configuration.

There's nothing to install, no `node_modules` to deploy, no build artifacts to coordinate, no relative paths to think about. The entire app — framework code, stylesheets, images, everything — lives in that one file.

## Truly one file

Normally, distributing a web page means managing a folder of assets — the HTML, the JavaScript bundles, the CSS files, the images. Move the HTML without the rest and everything breaks. Browsers have tried to solve this before: Safari's `.webarchive` and `.mhtml` are supposed to save a page as a single file, but in practice they unpack into a folder of loose files on your computer — defeating the purpose.

Standalone HTML is different. The output is a plain `.html` file. Not an archive. Not a folder. One file, with everything inside it. Every image, every font, every line of CSS and JavaScript is embedded directly in the HTML using standard `<style>` tags, `<script>` tags, and `data:` URIs. Any browser can open it. Any server can host it. Any file host can store it.

This makes it practical to distribute web pages the same way you'd distribute a PDF — as a single file you can move, copy, upload, or share without worrying about broken paths or missing assets.

## Quick start

<CodeGroup>
  ```html index.html icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}}
  <!doctype html>
  <html>
    <head>
      <link rel="stylesheet" href="./styles.css" />
    </head>
    <body>
      <div id="root"></div>
      <script src="./app.tsx"></script>
    </body>
  </html>
  ```

  ```tsx app.tsx icon="https://mintcdn.com/bun-1dd33a4e/nIz6GtMH5K-dfXeV/icons/typescript.svg?fit=max&auto=format&n=nIz6GtMH5K-dfXeV&q=85&s=5d73d76daf7eb7b158469d8c30d349b0" theme={"theme":{"light":"github-light","dark":"dracula"}}
  import React from "react";
  import { createRoot } from "react-dom/client";

  function App() {
    return <h1>Hello from a single HTML file!</h1>;
  }

  createRoot(document.getElementById("root")!).render(<App />);
  ```

  ```css styles.css icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}}
  body {
    margin: 0;
    font-family: system-ui, sans-serif;
    background: #f5f5f5;
  }
  ```
</CodeGroup>

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun build --compile --target=browser ./index.html --outdir=dist
```

Open `dist/index.html` — the React app works with no server.

## Everything gets inlined

Bun inlines every local asset it finds in your HTML. If it has a relative path, it gets embedded into the output file. This isn't limited to images and stylesheets — it works with any file type.

### What gets inlined

| In your source                                   | In the output                                                            |
| ------------------------------------------------ | ------------------------------------------------------------------------ |
| `<script src="./app.tsx">`                       | `<script type="module">...bundled code...</script>`                      |
| `<link rel="stylesheet" href="./styles.css">`    | `<style>...bundled CSS...</style>`                                       |
| `<img src="./logo.png">`                         | `<img src="data:image/png;base64,...">`                                  |
| `<img src="./icon.svg">`                         | `<img src="data:image/svg+xml;base64,...">`                              |
| `<video src="./demo.mp4">`                       | `<video src="data:video/mp4;base64,...">`                                |
| `<audio src="./click.wav">`                      | `<audio src="data:audio/wav;base64,...">`                                |
| `<source src="./clip.webm">`                     | `<source src="data:video/webm;base64,...">`                              |
| `<video poster="./thumb.jpg">`                   | `<video poster="data:image/jpeg;base64,...">`                            |
| `<link rel="icon" href="./favicon.ico">`         | `<link rel="icon" href="data:image/x-icon;base64,...">`                  |
| `<link rel="manifest" href="./app.webmanifest">` | `<link rel="manifest" href="data:application/manifest+json;base64,...">` |
| CSS `url("./bg.png")`                            | CSS `url(data:image/png;base64,...)`                                     |
| CSS `@import "./reset.css"`                      | Flattened into the `<style>` tag                                         |
| CSS `url("./font.woff2")`                        | CSS `url(data:font/woff2;base64,...)`                                    |
| JS `import "./styles.css"`                       | Merged into the `<style>` tag                                            |

Images, fonts, WASM binaries, videos, audio files, SVGs — any file referenced by a relative path gets base64-encoded into a `data:` URI and embedded directly in the HTML. The MIME type is automatically detected from the file extension.

External URLs (like CDN links or absolute URLs) are left untouched.

## Using with React

React apps work out of the box. Bun handles JSX transpilation and npm package resolution automatically.

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun install react react-dom
```

<CodeGroup>
  ```html index.html icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}}
  <!doctype html>
  <html>
    <head>
      <meta charset="utf-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <title>My App</title>
      <link rel="stylesheet" href="./styles.css" />
    </head>

From jarle/bun-skills, MIT.

More from jarle/bun-skills