Menu
Build static sites, landing pages, and web applications with Bun's bundler
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Configure a private registry for an organization scope with bun install
Speed up JavaScript execution with bytecode caching in Bun's bundler
Bun's bundler has built-in support for CSS with modern features
Migration guide from esbuild to Bun's bundler
Generate standalone executables from TypeScript or JavaScript files with Bun
Build fullstack applications with Bun's integrated dev server that bundles frontend assets and handles API routes
| name | Bun HTML & static sites |
| description | Build static sites, landing pages, and web applications with Bun's bundler |
Build static sites, landing pages, and web applications with Bun's bundler
Bun's bundler has first-class support for HTML. Build static sites, landing pages, and web applications with zero configuration. Just point Bun at your HTML file and it handles everything else.
<!doctype html>
<html>
<head>
<link rel="stylesheet" href="./styles.css" />
<script src="./app.ts" type="module"></script>
</head>
<body>
<img src="./logo.png" />
</body>
</html>
To get started, pass HTML files to bun.
bun ./index.html
Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts
Bun's development server provides powerful features with zero configuration:
tsconfig.json for paths, JSX options, experimental decorators, and more<link> tags and @import statementsWhen you pass a single .html file to Bun, Bun will use it as a fallback route for all paths. This makes it perfect for single page apps that use client-side routing:
bun index.html
Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts
Your React or other SPA will work out of the box — no configuration needed. All routes like /about, /users/123, etc. will serve the same HTML file, letting your client-side router handle the navigation.
<!doctype html>
<html>
<head>
<title>My SPA</title>
<script src="./app.tsx" type="module"></script>
</head>
<body>
<div id="root"></div>
</body>
</html>
Some projects have several separate routes or HTML files as entry points. To support multiple entry points, pass them all to bun:
bun ./index.html ./about.html
Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
/ ./index.html
/about ./about.html
Press h + Enter to show shortcuts
This will serve:
index.html at /about.html at /aboutTo specify multiple files, you can use glob patterns that end in .html:
bun ./**/*.html
Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
/ ./index.html
/about ./about.html
Press h + Enter to show shortcuts
The base path is chosen from the longest common prefix among all the files.
bun ./index.html ./about/index.html ./about/foo/index.html
Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Routes:
/ ./index.html
/about ./about/index.html
/about/foo ./about/foo/index.html
Press h + Enter to show shortcuts
Bun's transpiler natively implements JavaScript, TypeScript, and JSX support. Learn more about loaders in Bun.
Bun's transpiler is also used at runtime.
You can use ESM and CJS in your JavaScript, TypeScript, and JSX files. Bun will handle the transpilation and bundling automatically.
There is no pre-build or separate optimization step. It's all done at the same time.
Learn more about module resolution in Bun.
Bun's CSS parser is also natively implemented (clocking in around 58,000 lines of Zig).
It's also a CSS bundler. You can use @import in your CSS files to import other CSS files.
For example:
```css styles.css icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}} @import "./abc.css";.container { background-color: blue; }
```css abc.css icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}}
body {
background-color: red;
}
This outputs:
body {
background-color: red;
}
.container {
background-color: blue;
}
You can reference local assets in your CSS files.
body {
background-image: url("./logo.png");
}
This will copy ./logo.png to the output directory and rewrite the path in the CSS file to include a content hash.
body {
background-image: url("./logo-[ABC123].png");
}
To associate a CSS file with a JavaScript file, you can import it in your JavaScript file.
import "./styles.css";
import "./more-styles.css";
This generates ./app.css and ./app.js in the output directory. All CSS files imported from JavaScript will be bundled into a single CSS file per entry point. If you import the same CSS file from multiple JavaScript files, it will only be included once in the output CSS file.
The dev server supports plugins.
To use TailwindCSS, install the bun-plugin-tailwind plugin:
# Or any npm client
bun install --dev bun-plugin-tailwind
Then, add the plugin to your bunfig.toml:
[serve.static]
plugins = ["bun-plugin-tailwind"]
Then, reference TailwindCSS in your HTML via <link> tag, @import in CSS, or import in JavaScript.
Only one of those are necessary, not all three.
Bun can replace process.env.* references in your JavaScript and TypeScript with their actual values at build time. This is useful for injecting configuration like API URLs or feature flags into your frontend code.
To inline environment variables when using bun ./index.html, configure the env option in your bunfig.toml:
[serve.static]
env = "PUBLIC_*" # only inline env vars starting with PUBLIC_ (recommended)
# env = "inline" # inline all environment variables
# env = "disable" # disable env var replacement (default)
If an environment variable is not set, you may see runtime errors like ReferenceError: process is not defined in the browser.
Then run the dev server:
PUBLIC_API_URL=https://api.example.com bun ./index.html
When building static HTML for production, use the env option to inline environment variables:
# Only inline env vars with a specific prefix (recommended)
bun build ./index.html --outdir=dist --env=PUBLIC_*
```
// Only inline env vars with a specific prefix (recommended)
await Bun.build({
entrypoints: ["./index.html"],
outdir: "./dist",
env: "PUBLIC_*", // [!code highlight]
});
```
Given this source file:
const apiUrl = process.env.PUBLIC_API_URL;
console.log(`API URL: ${apiUrl}`);
And running with PUBLIC_API_URL=https://api.example.com:
PUBLIC_API_URL=https://api.example.com bun build ./index.html --outdir=dist --env=PUBLIC_*
The bundled output will contain:
const apiUrl = "https://api.example.com";
console.log(`API URL: ${apiUrl}`);
Bun's dev server supports streaming console logs from the browser to the terminal.
To enable, pass the --console CLI flag.
bun ./index.html --console
Bun v1.3.3
ready in 6.62ms
→ http://localhost:3000/
Press h + Enter to show shortcuts
Each call to console.log or console.error will be broadcast to the terminal that started the server. This is useful to see errors from the browser in the same place you run your server. This is also useful for AI agents that watch terminal output.
Internally, this reuses the existing WebSocket connection from hot module reloading to send the logs.
Bun's frontend dev server has support for Automatic Workspace Folders in Chrome DevTools, which lets you save edits to files in the browser.
While the server is running:
o + Enter - Open in browserc + Enter - Clear consoleq + Enter (or Ctrl+C) - Quit serverWhen you're ready to deploy, use bun build to create optimized production bundles:
bun build's CLI.
You can run bun build --watch to watch for changes and rebuild automatically. This works nicely for library development.
You've never seen a watch mode this fast.
Need more control? Configure the bundler through the JavaScript API and use Bun's builtin HTMLRewriter to preprocess HTML.
await Bun.build({
entrypoints: ["./index.html"],
outdir: "./dist",
minify: true,
plugins: [
{
// A plugin that makes every HTML tag lowercase
name: "lowercase-html-plugin",
setup({ onLoad }) {
const rewriter = new HTMLRewriter().on("*", {
element(element) {
element.tagName = element.tagName.toLowerCase();
},
text(element) {
element.replace(element.text.toLowerCase());
},
});
onLoad({ filter: /\.html$/ }, async args => {
const html = await Bun.file(args.path).text();
return {
// Bun's bundler will scan the HTML for <script> tags, <link rel="stylesheet"> tags, and other assets
// and bundle them automatically
contents: rewriter.transform(html),
loader: "html",
};
});
},
},
],
});
Bun automatically handles all common web assets:
<script src>) are run through Bun's JavaScript/TypeScript/JSX bundler<link rel="stylesheet">) are run through Bun's CSS parser & bundler<img>, <picture>) are copied and hashed<video>, <audio>, <source>) are copied and hashed<link> tag with an href attribute pointing to a local file is rewritten to the new path, and hashedAll paths are resolved relative to your HTML file, making it easy to organize your project however you want.
**This is a work in progress**{/* If you want to submit a PR, most of the code is here. You could even copy paste that file into your project and use it as a starting point. */}
This is a small wrapper around Bun's support for HTML imports in JavaScript.
You can bundle your entire frontend into a single self-contained .html file with no external dependencies using --compile --target=browser. All JavaScript, CSS, and images are inlined directly into the HTML.
bun build --compile --target=browser ./index.html --outdir=dist
Learn more in the Standalone HTML docs.
To add a backend to your frontend, you can use the "routes" option in Bun.serve.
Learn more in the full-stack docs.