Standalone HTML | Bun Docs

Bun can bundle your entire frontend into a single .html file with zero external dependencies. JavaScript, TypeScript, JSX, CSS, images, fonts, videos, WASM: Bun inlines everything into one file.

terminal

bun build --compile --target=browser ./index.html --outdir=dist

The output is a self-contained HTML document: no relative paths, no external files, no server required.

One file. Upload anywhere.#

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, 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 relative files to deal with
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

There's nothing to install, no node_modules to deploy, no build artifacts to coordinate, no relative paths to think about.

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 Chrome's .mhtml save a page as a single file. In practice, only some browsers can open them, which defeats the purpose.

Standalone HTML output is a plain .html file: not an archive, not a folder. Bun embeds every image, every font, and every line of CSS and JavaScript directly in the HTML using standard <style> tags, <script> tags, and data: URIs. Any browser can open it and any server can host it.

You can distribute the page the same way you'd distribute a PDF: a single file you can move, copy, upload, or share without worrying about broken paths or missing assets.

Quick start#

<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="./styles.css" />
  </head>
  <body>
    <div id="root"></div>
    <script src="./app.tsx"></script>
  </body>
</html>

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 />);

body {
  margin: 0;
  font-family: system-ui, sans-serif;
  background: #f5f5f5;
}

terminal

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: anything with a relative path, of any file type, is embedded into the output file.

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/x-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: Bun base64-encodes any file referenced by a relative path into a data: URI and embeds it directly in the HTML. Bun detects the MIME type from the file extension.

Bun leaves external URLs (like CDN links or absolute URLs) untouched.

Using with React#

React apps need no extra configuration: Bun transpiles JSX and resolves npm packages.

terminal

bun install react react-dom

<!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>
  <body>
    <div id="root"></div>
    <script src="./app.tsx"></script>
  </body>
</html>

import React, { useState } from "react";
import { createRoot } from "react-dom/client";
import { Counter } from "./components/Counter.tsx";

function App() {
  return (
    <main>
      <h1>Single-file React App</h1>
      <Counter />
    </main>
  );
}

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

import React, { useState } from "react";

export function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>Count: {count}</button>;
}

terminal

bun build --compile --target=browser ./index.html --outdir=dist

Bun bundles all of React, your components, and your CSS into dist/index.html. Upload that one file anywhere and it works.

Using with Tailwind CSS#

Install the plugin and reference Tailwind in your HTML or CSS:

terminal

bun install --dev bun-plugin-tailwind

<!doctype html>
<html>
  <head>
    <link rel="stylesheet" href="tailwindcss" />
  </head>
  <body class="bg-gray-100 flex items-center justify-center min-h-screen">
    <div id="root"></div>
    <script src="./app.tsx"></script>
  </body>
</html>

import React from "react";
import { createRoot } from "react-dom/client";

function App() {
  return (
    <div className="bg-white rounded-lg shadow-lg p-8 max-w-md">
      <h1 className="text-2xl font-bold text-gray-800">Hello Tailwind</h1>
      <p className="text-gray-600 mt-2">This is a single HTML file.</p>
    </div>
  );
}

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

Build with the plugin using the JavaScript API:

build.ts

await Bun.build({
  entrypoints: ["./index.html"],
  compile: true,
  target: "browser",
  outdir: "./dist",
  plugins: [require("bun-plugin-tailwind")],
});

terminal

bun run build.ts

Bun inlines the generated Tailwind CSS directly into the HTML file as a <style> tag.

How it works#

When you pass --compile --target=browser with an HTML entrypoint, Bun:

Parses the HTML and discovers all <script>, <link>, <img>, <video>, <audio>, <source>, and other asset references
Bundles all JavaScript/TypeScript/JSX into a single module
Bundles all CSS (including @import chains and CSS imported from JS) into a single stylesheet
Converts every relative asset reference into a base64 data: URI
Inlines the bundled JS as <script type="module"> before </body>
Inlines the bundled CSS as <style> in <head>
Outputs a single .html file with no external dependencies

Minification#

Add --minify to minify the JavaScript and CSS:

terminal

bun build --compile --target=browser --minify ./index.html --outdir=dist

Or with the JavaScript API:

build.ts

await Bun.build({
  entrypoints: ["./index.html"],
  compile: true,
  target: "browser",
  outdir: "./dist",
  minify: true,
});

JavaScript API#

Use Bun.build() to produce standalone HTML programmatically:

build.ts

const result = await Bun.build({
  entrypoints: ["./index.html"],
  compile: true,
  target: "browser",
  outdir: "./dist", // optional — omit to get output as BuildArtifact
  minify: true,
});

if (!result.success) {
  console.error("Build failed:");
  for (const log of result.logs) {
    console.error(log);
  }
} else {
  console.log("Built:", result.outputs[0].path);
}

When you omit outdir, the output is available as a BuildArtifact in result.outputs:

const result = await Bun.build({
  entrypoints: ["./index.html"],
  compile: true,
  target: "browser",
});

const html = await result.outputs[0].text();
await Bun.write("output.html", html);

Multiple HTML files#

You can pass multiple HTML files as entrypoints. Each produces its own standalone HTML file:

terminal

bun build --compile --target=browser ./index.html ./about.html --outdir=dist

Environment variables#

Use --env to inline environment variables into the bundled JavaScript:

terminal

API_URL=https://api.example.com bun build --compile --target=browser --env=inline ./index.html --outdir=dist

Bun replaces references to process.env.API_URL in your JavaScript with the literal value at build time.

Limitations#

Code splitting is not supported — --splitting cannot be used with --compile --target=browser
Large assets increase file size since they're base64-encoded (33% overhead vs the raw binary)
External URLs (CDN links, absolute URLs) stay as-is: Bun inlines only relative paths