My SPA

> ## Documentation Index > Fetch the complete documentation index at: https://bun-1dd33a4e-farm-ad2450b3-transpiler-cache-version-namespa.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # HTML & static sites > 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: point Bun at your HTML file and it bundles the scripts, stylesheets, and assets the file references. ```html title="index.html" icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}}

``` To get started, pass HTML files to `bun`. ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}} bun ./index.html ``` ``` Bun v1.3.3 ready in 6.62ms → http://localhost:3000/ Press h + Enter to show shortcuts ``` With no configuration, Bun's development server provides: * **Automatic Bundling** - Bundles and serves your HTML, JavaScript, and CSS * **Multi-Entry Support** - Handles multiple HTML entry points and glob entry points * **Modern JavaScript** - TypeScript & JSX support by default * **Smart Configuration** - Reads `tsconfig.json` for paths, JSX options, and experimental decorators * **Plugins** - Plugin support, including TailwindCSS * **ESM & CommonJS** - Use ESM and CommonJS in your JavaScript, TypeScript, and JSX files * **CSS Bundling & Minification** - Bundles CSS from `` tags and `@import` statements * **Asset Management** - Copies and hashes images and assets, and rewrites asset paths in JavaScript, CSS, and HTML ## Single Page Apps (SPA) When you pass a single `.html` file to Bun, Bun uses it as a fallback route for all paths. This suits single page apps that use client-side routing: ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}} 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 works with no configuration. Routes like `/about` and `/users/123` serve the same HTML file, so your client-side router handles the navigation. ```html title="index.html" icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}} My SPA

``` ## Multi-page apps (MPA) Some projects have several separate routes or HTML files as entry points. To support multiple entry points, pass them all to `bun`: ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}} bun ./index.html ./about.html ``` ```txt theme={"theme":{"light":"github-light","dark":"dracula"}} Bun v1.3.3 ready in 6.62ms → http://localhost:3000/ Routes: / ./index.html /about ./about.html Press h + Enter to show shortcuts ``` This serves: * `index.html` at `/` * `about.html` at `/about` ### Glob patterns To specify multiple files, use a glob pattern that ends in `.html`: ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}} 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 ``` ### Path normalization Bun chooses the base path from the longest common prefix among all the files. ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}} 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 ``` ## JavaScript, TypeScript, and JSX Bun's transpiler natively implements JavaScript, TypeScript, and JSX support. See [loaders](/bundler/loaders). Bun's transpiler is also used at runtime. ### ES Modules & CommonJS You can use ESM and CommonJS in your JavaScript, TypeScript, and JSX files. Bun transpiles and bundles them automatically. There is no pre-build or separate optimization step. It's all done at the same time. See [module resolution](/runtime/module-resolution). ## CSS Bun's CSS parser is also natively implemented (about 70,000 lines of Rust). 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: ```css styles.css icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}} body { background-color: red; } .container { background-color: blue; } ``` ### Referencing local assets in CSS ```css styles.css icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}} body { background-image: url("./logo.png"); } ``` Bun copies `./logo.png` to the output directory and rewrites the path in the CSS file to include a content hash. ```css styles.css icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}} body { background-image: url("./logo-[ABC123].png"); } ``` ### Importing CSS in JavaScript To associate a CSS file with a JavaScript file, import it from the JavaScript file. ```ts app.ts icon="https://mintcdn.com/bun-1dd33a4e-farm-ad2450b3-transpiler-cache-version-namespa/pVrMBuZvntvIe2NO/icons/typescript.svg?fit=max&auto=format&n=pVrMBuZvntvIe2NO&q=85&s=81fcaf3ac2cead5d758f3588a492f46a" theme={"theme":{"light":"github-light","dark":"dracula"}} import "./styles.css"; import "./more-styles.css"; ``` This generates `./app.css` and `./app.js` in the output directory. All CSS files imported from JavaScript are bundled into a single CSS file per entry point. If you import the same CSS file from multiple JavaScript files, it is only included once in the output CSS file. ## Plugins The dev server supports plugins. ### Tailwind CSS To use TailwindCSS, install the `bun-plugin-tailwind` plugin: ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}} # Or any npm client bun install --dev bun-plugin-tailwind ``` Then, add the plugin to your `bunfig.toml`: ```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}} [serve.static] plugins = ["bun-plugin-tailwind"] ``` Then, reference TailwindCSS in your HTML with a `` tag, an `@import` in CSS, or an import in JavaScript. ```html title="index.html" icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}} ``` ```css title="styles.css" icon="file-code" theme={"theme":{"light":"github-light","dark":"dracula"}} @import "tailwindcss"; ``` ```ts title="app.ts" icon="https://mintcdn.com/bun-1dd33a4e-farm-ad2450b3-transpiler-cache-version-namespa/pVrMBuZvntvIe2NO/icons/typescript.svg?fit=max&auto=format&n=pVrMBuZvntvIe2NO&q=85&s=81fcaf3ac2cead5d758f3588a492f46a" theme={"theme":{"light":"github-light","dark":"dracula"}} import "tailwindcss"; ``` Only one of these is necessary, not all three. ## Inline environment variables Bun can replace `process.env.*` references in your JavaScript and TypeScript with their actual values at build time. Use this to inject configuration like API URLs or feature flags into your frontend code. ### Dev server (runtime) To inline environment variables when using `bun ./index.html`, configure the `env` option in your `bunfig.toml`: ```toml title="bunfig.toml" icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}} [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) ``` This only works with literal `process.env.FOO` references, not `import.meta.env` or indirect access like `const env = process.env; env.FOO`. 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: ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}} PUBLIC_API_URL=https://api.example.com bun ./index.html ``` ### Build for production When building static HTML for production, use the `env` option to inline environment variables: ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}} # Inline all environment variables bun build ./index.html --outdir=dist --env=inline # Only inline env vars with a specific prefix (recommended) bun build ./index.html --outdir=dist --env=PUBLIC_* ``` ```ts title="build.ts" icon="https://mintcdn.com/bun-1dd33a4e-farm-ad2450b3-transpiler-cache-version-namespa/pVrMBuZvntvIe2NO/icons/typescript.svg?fit=max&auto=format&n=pVrMBuZvntvIe2NO&q=85&s=81fcaf3ac2cead5d758f3588a492f46a" theme={"theme":{"light":"github-light","dark":"dracula"}} // Inline all environment variables await Bun.build({ entrypoints: ["./index.html"], outdir: "./dist", env: "inline", // [!code highlight] }); // Only inline env vars with a specific prefix (recommended) await Bun.build({ entrypoints: ["./index.html"], outdir: "./dist", env: "PUBLIC_*", // [!code highlight] }); ``` ### Example Given this source file: ```ts title="app.ts" icon="https://mintcdn.com/bun-1dd33a4e-farm-ad2450b3-transpiler-cache-version-namespa/pVrMBuZvntvIe2NO/icons/typescript.svg?fit=max&auto=format&n=pVrMBuZvntvIe2NO&q=85&s=81fcaf3ac2cead5d758f3588a492f46a" theme={"theme":{"light":"github-light","dark":"dracula"}} const apiUrl = process.env.PUBLIC_API_URL; console.log(`API URL: ${apiUrl}`); ``` And running with `PUBLIC_API_URL=https://api.example.com`: ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}} PUBLIC_API_URL=https://api.example.com bun build ./index.html --outdir=dist --env=PUBLIC_* ``` The bundled output contains: ```js title="dist/app.js" icon="https://mintcdn.com/bun-1dd33a4e-farm-ad2450b3-transpiler-cache-version-namespa/pVrMBuZvntvIe2NO/icons/javascript.svg?fit=max&auto=format&n=pVrMBuZvntvIe2NO&q=85&s=69baa493b279efc720ede6b18e487cab" theme={"theme":{"light":"github-light","dark":"dracula"}} const apiUrl = "https://api.example.com"; console.log(`API URL: ${apiUrl}`); ``` ## Echo console logs from browser to terminal Bun's dev server can stream console logs from the browser to the terminal. To enable this, pass the `--console` CLI flag. ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}} 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` is broadcast to the terminal that started the server, so browser errors show up in the same place you run your server. This also helps AI agents that watch terminal output. Internally, this reuses the existing WebSocket connection from hot module replacement (HMR) to send the logs. ## Edit files in the browser Bun's frontend dev server supports Automatic Workspace Folders in Chrome DevTools, so you can save edits to files from the browser. ## Keyboard Shortcuts While the server is running: * `o + Enter` - Open in browser * `c + Enter` - Clear console * `q + Enter` (or `Ctrl+C`) - Quit server ## Build for Production When you're ready to deploy, use `bun build` to create optimized production bundles: ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}} bun build ./index.html --minify --outdir=dist ``` ```ts title="build.ts" icon="https://mintcdn.com/bun-1dd33a4e-farm-ad2450b3-transpiler-cache-version-namespa/pVrMBuZvntvIe2NO/icons/typescript.svg?fit=max&auto=format&n=pVrMBuZvntvIe2NO&q=85&s=81fcaf3ac2cead5d758f3588a492f46a" theme={"theme":{"light":"github-light","dark":"dracula"}} await Bun.build({ entrypoints: ["./index.html"], outdir: "./dist", minify: true, }); ``` Plugins are only supported through `Bun.build`'s API or through `bunfig.toml` with the frontend dev server, not through `bun build`'s CLI. ### Watch Mode Run `bun build --watch` to watch for changes and rebuild automatically. This works well for library development. You've never seen a watch mode this fast. ## Plugin API For more control, configure the bundler through the JavaScript API and use Bun's built-in `HTMLRewriter` to preprocess HTML. ```ts title="build.ts" icon="https://mintcdn.com/bun-1dd33a4e-farm-ad2450b3-transpiler-cache-version-namespa/pVrMBuZvntvIe2NO/icons/typescript.svg?fit=max&auto=format&n=pVrMBuZvntvIe2NO&q=85&s=81fcaf3ac2cead5d758f3588a492f46a" theme={"theme":{"light":"github-light","dark":"dracula"}} 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