> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/zhcndoc/bun/llms.txt
> Use this file to discover all available pages before exploring further.
# HTML
> Process HTML files with bundled assets using Bun's bundler
Bun's bundler can process HTML files as entrypoints, automatically bundling all referenced assets (scripts, stylesheets, images, etc.) and updating the HTML to reference the bundled files.
## Basic usage
Given an HTML file:
```html index.html theme={null}
My App
```
Bundle it with:
```bash theme={null}
bun build ./index.html --outdir ./dist
```
The output will be:
```text theme={null}
dist/
index.html
app-[hash].js
styles-[hash].css
```
And the HTML will be updated to reference the hashed files:
```html dist/index.html theme={null}
My App
```
## Supported elements
Bun's HTML processor recognizes and bundles the following elements:
### Scripts
```html theme={null}
```
### Stylesheets
```html theme={null}
```
### Images
```html theme={null}
```
### Other assets
```html theme={null}
```
## External URLs
External URLs (those starting with `http://`, `https://`, or `//`) are preserved as-is:
```html theme={null}
```
## Public path
Use `--public-path` to prefix all asset URLs:
```bash theme={null}
bun build ./index.html --outdir ./dist --public-path /assets/
```
```html Output theme={null}
```
This is useful for CDN deployments:
```bash theme={null}
bun build ./index.html --outdir ./dist --public-path https://cdn.example.com/
```
## Minification
HTML is minified when `--minify` is enabled:
```bash theme={null}
bun build ./index.html --outdir ./dist --minify
```
This removes:
* Whitespace between elements
* HTML comments (except conditional comments)
* Unnecessary quotes around attribute values
* Optional closing tags
## Multiple HTML files
You can bundle multiple HTML files:
```bash theme={null}
bun build ./index.html ./about.html ./contact.html --outdir ./dist
```
Each HTML file becomes an independent entrypoint with its own set of bundled assets.
## Code splitting
When multiple HTML files share JavaScript or CSS, those assets can be code-split:
```bash theme={null}
bun build ./index.html ./about.html --outdir ./dist --splitting
```
Shared code is extracted into separate chunk files, and each HTML file references the appropriate chunks.
## JavaScript API
```ts theme={null}
await Bun.build({
entrypoints: ["./index.html"],
outdir: "./dist",
minify: true,
publicPath: "/assets/",
});
```
## Dynamic HTML generation
For server-side rendering or dynamic HTML generation, import HTML files in your JavaScript:
```ts server.ts theme={null}
import html from "./index.html";
const server = Bun.serve({
port: 3000,
fetch(req) {
return new Response(html, {
headers: { "Content-Type": "text/html" },
});
},
});
```
When bundled with `--target=bun`, the HTML import resolves to a manifest object for serving pre-bundled assets efficiently.
## Full-stack applications
Combine HTML processing with server-side code:
```ts server.ts theme={null}
import html from "./index.html";
const server = Bun.serve({
port: 3000,
fetch(req) {
const url = new URL(req.url);
// Serve the HTML for the root path
if (url.pathname === "/") {
return new Response(html, {
headers: { "Content-Type": "text/html" },
});
}
// API routes
if (url.pathname === "/api/data") {
return Response.json({ message: "Hello!" });
}
return new Response("Not found", { status: 404 });
},
});
console.log(`Server running at http://localhost:${server.port}`);
```
Build for production:
```bash theme={null}
bun build ./server.ts --outdir ./dist --target=bun --compile
```
This creates a standalone executable with all assets embedded.
## Templates and components
For more complex HTML generation, use template literals or JSX:
```tsx server.tsx theme={null}
function Layout({ children }: { children: any }) {
return (
My App
{children}
);
}
const server = Bun.serve({
port: 3000,
fetch(req) {
const html = (
Welcome!
);
return new Response(html, {
headers: { "Content-Type": "text/html" },
});
},
});
```
## Asset hashing
All bundled assets are content-hashed by default:
```
app-a1b2c3d4.js
styles-e5f6g7h8.css
logo-i9j0k1l2.png
```
This enables:
* Long-term caching (files can be cached forever)
* Cache invalidation (changing content changes the hash)
* Parallel loading (no version conflicts)
## Source maps
Generate source maps for JavaScript bundles:
```bash theme={null}
bun build ./index.html --outdir ./dist --sourcemap=external
```
Source map files are placed alongside their corresponding bundles:
```
dist/
index.html
app-a1b2c3.js
app-a1b2c3.js.map
```
## Examples
### Static site
```html index.html theme={null}
Static Site
```
```bash theme={null}
bun build ./index.html --outdir ./dist --minify
```
### Single-page application
```html index.html theme={null}
SPA
```
```tsx src/main.tsx theme={null}
import { render } from "react-dom";
import { App } from "./App";
render(, document.getElementById("app"));
```
```bash theme={null}
bun build ./index.html --outdir ./dist --minify --splitting
```
### Progressive Web App
```html index.html theme={null}
PWA
```
```bash theme={null}
bun build ./index.html --outdir ./dist --minify --public-path /
```
## Troubleshooting
### Paths not resolving
Make sure all asset paths are relative to the HTML file:
```html theme={null}
```
### Assets not found
Check that the referenced files exist relative to the HTML file:
```text theme={null}
project/
index.html
app.ts
images/
logo.png
```
### External URLs bundled
Ensure external URLs start with `http://`, `https://`, or `//`:
```html theme={null}
```
### Inline scripts interfering
Inline scripts run immediately and might interfere with bundled modules. Use `type="module"` for modern code:
```html theme={null}
```
```
### Other assets
```html theme={null}
```
## External URLs
External URLs (those starting with `http://`, `https://`, or `//`) are preserved as-is:
```html theme={null}
```
## Public path
Use `--public-path` to prefix all asset URLs:
```bash theme={null}
bun build ./index.html --outdir ./dist --public-path /assets/
```
```html Output theme={null}
```
This is useful for CDN deployments:
```bash theme={null}
bun build ./index.html --outdir ./dist --public-path https://cdn.example.com/
```
## Minification
HTML is minified when `--minify` is enabled:
```bash theme={null}
bun build ./index.html --outdir ./dist --minify
```
This removes:
* Whitespace between elements
* HTML comments (except conditional comments)
* Unnecessary quotes around attribute values
* Optional closing tags
## Multiple HTML files
You can bundle multiple HTML files:
```bash theme={null}
bun build ./index.html ./about.html ./contact.html --outdir ./dist
```
Each HTML file becomes an independent entrypoint with its own set of bundled assets.
## Code splitting
When multiple HTML files share JavaScript or CSS, those assets can be code-split:
```bash theme={null}
bun build ./index.html ./about.html --outdir ./dist --splitting
```
Shared code is extracted into separate chunk files, and each HTML file references the appropriate chunks.
## JavaScript API
```ts theme={null}
await Bun.build({
entrypoints: ["./index.html"],
outdir: "./dist",
minify: true,
publicPath: "/assets/",
});
```
## Dynamic HTML generation
For server-side rendering or dynamic HTML generation, import HTML files in your JavaScript:
```ts server.ts theme={null}
import html from "./index.html";
const server = Bun.serve({
port: 3000,
fetch(req) {
return new Response(html, {
headers: { "Content-Type": "text/html" },
});
},
});
```
When bundled with `--target=bun`, the HTML import resolves to a manifest object for serving pre-bundled assets efficiently.
## Full-stack applications
Combine HTML processing with server-side code:
```ts server.ts theme={null}
import html from "./index.html";
const server = Bun.serve({
port: 3000,
fetch(req) {
const url = new URL(req.url);
// Serve the HTML for the root path
if (url.pathname === "/") {
return new Response(html, {
headers: { "Content-Type": "text/html" },
});
}
// API routes
if (url.pathname === "/api/data") {
return Response.json({ message: "Hello!" });
}
return new Response("Not found", { status: 404 });
},
});
console.log(`Server running at http://localhost:${server.port}`);
```
Build for production:
```bash theme={null}
bun build ./server.ts --outdir ./dist --target=bun --compile
```
This creates a standalone executable with all assets embedded.
## Templates and components
For more complex HTML generation, use template literals or JSX:
```tsx server.tsx theme={null}
function Layout({ children }: { children: any }) {
return (
```
### Assets not found
Check that the referenced files exist relative to the HTML file:
```text theme={null}
project/
index.html
app.ts
images/
logo.png
```
### External URLs bundled
Ensure external URLs start with `http://`, `https://`, or `//`:
```html theme={null}
```
### Inline scripts interfering
Inline scripts run immediately and might interfere with bundled modules. Use `type="module"` for modern code:
```html theme={null}
```