Fullstack dev server

To get started, import HTML files and pass them to the routes option in Bun.serve().

app.ts

import { serve, sql } from "bun";
import dashboard from "./dashboard.html";
import homepage from "./index.html";

const server = serve({
  routes: {
    // ** HTML imports **
    // Bundle & route index.html to "/". This uses HTMLRewriter to scan
    // the HTML for `<script>` and `<link>` tags, runs Bun's JavaScript
    // & CSS bundler on them, transpiles any TypeScript, JSX, and TSX,
    // downlevels CSS with Bun's CSS parser and serves the result.
    "/": homepage,
    // Bundle & route dashboard.html to "/dashboard"
    "/dashboard": dashboard,

    // ** API endpoints ** (Bun v1.2.3+ required)
    "/api/users": {
      async GET(req) {
        const users = await sql`SELECT * FROM users`;
        return Response.json(users);
      },
      async POST(req) {
        const { name, email } = await req.json();
        const [user] = await sql`INSERT INTO users (name, email) VALUES (${name}, ${email}) RETURNING *`;
        return Response.json(user);
      },
    },
    "/api/users/:id": async req => {
      const { id } = req.params;
      const [user] = await sql`SELECT * FROM users WHERE id = ${id}`;
      return Response.json(user);
    },
  },

  // Enable development mode for:
  // - Detailed error messages
  // - Hot reloading (Bun v1.2.3+ required)
  development: true,
});

console.log(`Listening on ${server.url}`);

terminal

bun run app.ts

HTML Routes#

HTML Imports as Routes#

To specify entrypoints to your frontend, import HTML files into your JavaScript/TypeScript/TSX/JSX files.

app.ts

import dashboard from "./dashboard.html";
import homepage from "./index.html";

Pass the imported HTML files as routes to Bun.serve().

app.ts

Bun.serve({
  routes: {
    "/": homepage,
    "/dashboard": dashboard,
  },

  fetch(req) {
    // ... api requests
  },
});

When you make a request to /dashboard or /, Bun automatically bundles the <script> and <link> tags in the HTML files, exposes them as static routes, and serves the result.

HTML Processing Example#

An index.html file like this:

index.html

<!DOCTYPE html>
<html>
  <head>
    <title>Home</title>
    <link rel="stylesheet" href="./reset.css" />
    <link rel="stylesheet" href="./styles.css" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="./sentry-and-preloads.ts"></script>
    <script type="module" src="./my-app.tsx"></script>
  </body>
</html>

Becomes something like this:

index.html

<!DOCTYPE html>
<html>
  <head>
    <title>Home</title>
    <link rel="stylesheet" href="/index-[hash].css" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/index-[hash].js"></script>
  </body>
</html>

React Integration#

To use React in your client-side code, import react-dom/client and render your app.

import dashboard from "../public/dashboard.html";
import { serve } from "bun";

serve({
  routes: {
    "/": dashboard,
  },
  async fetch(req) {
    // ...api requests
    return new Response("hello world");
  },
});

import { createRoot } from "react-dom/client";
import App from "./app";

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

<!DOCTYPE html>
<html>
  <head>
    <title>Dashboard</title>
    <link rel="stylesheet" href="../src/styles.css" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="../src/frontend.tsx"></script>
  </body>
</html>

import { useState } from "react";

export default function App() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <h1>Dashboard</h1>
      <button onClick={() => setCount(count + 1)}>Count: {count}</button>
    </div>
  );
}

Development Mode#

When building locally, enable development mode by setting development: true in Bun.serve().

src/backend.ts

import homepage from "./index.html";
import dashboard from "./dashboard.html";

Bun.serve({
  routes: {
    "/": homepage,
    "/dashboard": dashboard,
  },

  development: true,

  fetch(req) {
    // ... api requests
  },
});

Development Mode Features#

When development is true, Bun:

Includes the SourceMap header in the response so that devtools can show the original source code
Disables minification
Re-bundles assets on each request to a .html file
Enables hot module reloading (unless you set hmr: false)

Advanced Development Configuration#

To echo console logs from the browser to the terminal, pass console: true in the development object in Bun.serve().

src/backend.ts

import homepage from "./index.html";

Bun.serve({
  // development can also be an object.
  development: {
    // Enable Hot Module Reloading
    hmr: true,

    // Echo console logs from the browser to the terminal
    console: true,
  },

  routes: {
    "/": homepage,
  },
});

Bun sends the logs over the existing HMR WebSocket connection.

Development vs Production#

Feature	Development	Production
Source maps	✅ Enabled	❌ Disabled
Minification	❌ Disabled	✅ Enabled
Hot reloading	✅ Enabled	❌ Disabled
Asset bundling	🔄 On each request	💾 Cached
Console logging	🖥️ Browser → Terminal	❌ Disabled
Error details	📝 Detailed	🔒 Minimal

Production Mode#

Hot reloading and development: true help you iterate quickly, but in production your server should be as fast as possible and have as few external dependencies as possible.

Ahead of Time Bundling (Recommended)#

As of Bun v1.2.17, you can use Bun.build or bun build to bundle your fullstack application ahead of time.

terminal

bun build --target=bun --production --outdir=dist ./src/index.ts

When Bun's bundler sees an HTML import from server-side code, it bundles the referenced JavaScript/TypeScript/TSX/JSX and CSS files into a manifest object that Bun.serve() can use to serve the assets.

src/backend.ts

import { serve } from "bun";
import index from "./index.html";

serve({
  routes: { "/": index },
});

Runtime Bundling#

If you'd rather not add a build step, set development: false in Bun.serve().

With this setting, Bun:

Enables in-memory caching of bundled assets. Bun bundles assets lazily on the first request to an .html file and caches the result in memory until the server restarts.
Enables Cache-Control and ETag headers
Minifies JavaScript/TypeScript/TSX/JSX files

src/backend.ts

import { serve } from "bun";
import homepage from "./index.html";

serve({
  routes: {
    "/": homepage,
  },

  // Production mode
  development: false,
});

API Routes#

HTTP Method Handlers#

Define API endpoints with HTTP method handlers:

src/backend.ts

import { serve } from "bun";

serve({
  routes: {
    "/api/users": {
      async GET(req) {
        // Handle GET requests
        const users = await getUsers();
        return Response.json(users);
      },

      async POST(req) {
        // Handle POST requests
        const userData = await req.json();
        const user = await createUser(userData);
        return Response.json(user, { status: 201 });
      },

      async PUT(req) {
        // Handle PUT requests
        const userData = await req.json();
        const user = await updateUser(userData);
        return Response.json(user);
      },

      async DELETE(req) {
        // Handle DELETE requests
        await deleteUser(req.params.id);
        return new Response(null, { status: 204 });
      },
    },
  },
});

Dynamic Routes#

Use URL parameters in your routes:

src/backend.ts

serve({
  routes: {
    // Single parameter
    "/api/users/:id": async req => {
      const { id } = req.params;
      const user = await getUserById(id);
      return Response.json(user);
    },

    // Multiple parameters
    "/api/users/:userId/posts/:postId": async req => {
      const { userId, postId } = req.params;
      const post = await getPostByUser(userId, postId);
      return Response.json(post);
    },

    // Wildcard routes
    "/api/files/*": async req => {
      const filePath = req.params["*"];
      const file = await getFile(filePath);
      return new Response(file);
    },
  },
});

Request Handling#

src/backend.ts

serve({
  routes: {
    "/api/data": {
      async POST(req) {
        // Parse JSON body
        const body = await req.json();

        // Access headers
        const auth = req.headers.get("Authorization");

        // Access URL parameters
        const { id } = req.params;

        // Access query parameters
        const url = new URL(req.url);
        const page = url.searchParams.get("page") || "1";

        // Return response
        return Response.json({
          message: "Data processed",
          page: parseInt(page),
          authenticated: !!auth,
        });
      },
    },
  },
});

Plugins#

Bun also supports bundler plugins when bundling static routes.

To configure plugins for Bun.serve, add a plugins array in the [serve.static] section of your bunfig.toml.

TailwindCSS Plugin#

To use TailwindCSS, install the tailwindcss package and the bun-plugin-tailwind plugin.

terminal

bun add tailwindcss bun-plugin-tailwind

bunfig.toml

[serve.static]
plugins = ["bun-plugin-tailwind"]

You can now use TailwindCSS utility classes in your HTML and CSS files. Import tailwindcss somewhere in your project:

index.html

<!doctype html>
<html>
  <head>
    
    <link rel="stylesheet" href="tailwindcss" />
  </head>
  <!-- the rest of your HTML... -->
</html>

Alternatively, you can import TailwindCSS in your CSS file:

style.css

@import "tailwindcss";

.custom-class {
  @apply bg-red-500 text-white;
}

index.html

<!doctype html>
<html>
  <head>
    
    <link rel="stylesheet" href="./style.css" />
  </head>
  <!-- the rest of your HTML... -->
</html>

Custom Plugins#

The plugins array accepts any JS file or module that exports a valid bundler plugin object (an object with a name and a setup field):

bunfig.toml

[serve.static]
plugins = ["./my-plugin-implementation.ts"]

my-plugin-implementation.ts

import type { BunPlugin } from "bun";

const myPlugin: BunPlugin = {
  name: "my-custom-plugin",
  setup(build) {
    // Plugin implementation
    build.onLoad({ filter: /\.custom$/ }, async args => {
      const text = await Bun.file(args.path).text();
      return {
        contents: `export default ${JSON.stringify(text)};`,
        loader: "js",
      };
    });
  },
};

export default myPlugin;

Bun lazily resolves and loads each plugin and uses them to bundle your routes.

Plugins live in bunfig.toml so that the bun build CLI, once it supports them, can know statically which plugins are in use. These plugins work in Bun.build()'s JS API, but not yet in the CLI.

Inline Environment Variables#

Bun can replace process.env.* references in your frontend JavaScript and TypeScript with their values at build time. Configure the env option in your bunfig.toml:

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)

Bun only replaces 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.

See HTML & static sites for build-time configuration and examples.

Sourcemaps#

In development, Bun generates linked sourcemaps for bundled routes and serves them alongside the JavaScript and CSS chunks. In production (development: false), sourcemaps are disabled by default so the server does not expose your original source code.

To override the default, set the sourcemap option in your bunfig.toml:

bunfig.toml

[serve.static]
sourcemap = "linked" # serve sourcemaps in production too
# sourcemap = "inline"   # embed sourcemaps in the chunks
# sourcemap = "external" # emit .map files without a sourceMappingURL comment
# sourcemap = false      # never generate sourcemaps

How It Works#

Bun uses HTMLRewriter to scan for <script> and <link> tags in HTML files and uses them as entrypoints for Bun's bundler. Bun then generates an optimized bundle for the JavaScript/TypeScript/TSX/JSX and CSS files and serves the result.

Processing Pipeline#

1. <script> Processing

Transpiles TypeScript, JSX, and TSX in <script> tags
Bundles imported dependencies
Generates sourcemaps for debugging in development
Minifies when development is not true in Bun.serve()

index.html

<script type="module" src="./counter.tsx"></script>

2. <link> Processing

Processes CSS imports and <link> tags
Concatenates CSS files
Rewrites url and asset paths to include content-addressable hashes in URLs

index.html

<link rel="stylesheet" href="./styles.css" />

3. <img> & Asset Processing

Rewrites links to assets to include content-addressable hashes in URLs
Inlines small assets in CSS files into data: URLs, reducing the total number of HTTP requests sent over the wire

4. HTML Rewriting

Combines all <script> tags into a single <script> tag with a content-addressable hash in the URL
Combines all <link> tags into a single <link> tag with a content-addressable hash in the URL
Outputs a new HTML file

5. Serving

Exposes all the output files from the bundler as static routes, using the same mechanism internally as when you pass a Response object to routes in Bun.serve().
This pipeline works similarly to how Bun.build processes HTML files.

Complete Example#

server.ts

import { serve } from "bun";
import { Database } from "bun:sqlite";
import homepage from "./public/index.html";
import dashboard from "./public/dashboard.html";

// Initialize database
const db = new Database("app.db");
db.exec(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
  )
`);

const server = serve({
  routes: {
    // Frontend routes
    "/": homepage,
    "/dashboard": dashboard,

    // API routes
    "/api/users": {
      async GET() {
        const users = db.query("SELECT * FROM users").all();
        return Response.json(users);
      },

      async POST(req) {
        const { name, email } = await req.json();

        try {
          const result = db.query("INSERT INTO users (name, email) VALUES (?, ?) RETURNING *").get(name, email);

          return Response.json(result, { status: 201 });
        } catch (error) {
          return Response.json({ error: "Email already exists" }, { status: 400 });
        }
      },
    },

    "/api/users/:id": {
      async GET(req) {
        const { id } = req.params;
        const user = db.query("SELECT * FROM users WHERE id = ?").get(id);

        if (!user) {
          return Response.json({ error: "User not found" }, { status: 404 });
        }

        return Response.json(user);
      },

      async DELETE(req) {
        const { id } = req.params;
        const result = db.query("DELETE FROM users WHERE id = ?").run(id);

        if (result.changes === 0) {
          return Response.json({ error: "User not found" }, { status: 404 });
        }

        return new Response(null, { status: 204 });
      },
    },

    // Health check endpoint
    "/api/health": {
      GET() {
        return Response.json({
          status: "ok",
          timestamp: new Date().toISOString(),
        });
      },
    },
  },

  // Enable development mode
  development: {
    hmr: true,
    console: true,
  },

  // Fallback for unmatched routes
  fetch(req) {
    return new Response("Not Found", { status: 404 });
  },
});

console.log(`🚀 Server running on ${server.url}`);

public/index.html

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Fullstack Bun App</title>
    <link rel="stylesheet" href="../src/styles.css" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="../src/main.tsx"></script>
  </body>
</html>

src/main.tsx

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

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

src/App.tsx

import { useState, useEffect } from "react";

interface User {
  id: number;
  name: string;
  email: string;
  created_at: string;
}

export function App() {
  const [users, setUsers] = useState<User[]>([]);
  const [name, setName] = useState("");
  const [email, setEmail] = useState("");
  const [loading, setLoading] = useState(false);

  const fetchUsers = async () => {
    const response = await fetch("/api/users");
    const data = await response.json();
    setUsers(data);
  };

  const createUser = async (e: React.FormEvent) => {
    e.preventDefault();
    setLoading(true);

    try {
      const response = await fetch("/api/users", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ name, email }),
      });

      if (response.ok) {
        setName("");
        setEmail("");
        await fetchUsers();
      } else {
        const error = await response.json();
        alert(error.error);
      }
    } catch (error) {
      alert("Failed to create user");
    } finally {
      setLoading(false);
    }
  };

  const deleteUser = async (id: number) => {
    if (!confirm("Are you sure?")) return;

    try {
      const response = await fetch(`/api/users/${id}`, {
        method: "DELETE",
      });

      if (response.ok) {
        await fetchUsers();
      }
    } catch (error) {
      alert("Failed to delete user");
    }
  };

  useEffect(() => {
    fetchUsers();
  }, []);

  return (
    <div className="container">
      <h1>User Management</h1>

      <form onSubmit={createUser} className="form">
        <input type="text" placeholder="Name" value={name} onChange={e => setName(e.target.value)} required />
        <input type="email" placeholder="Email" value={email} onChange={e => setEmail(e.target.value)} required />
        <button type="submit" disabled={loading}>
          {loading ? "Creating..." : "Create User"}
        </button>
      </form>

      <div className="users">
        <h2>Users ({users.length})</h2>
        {users.map(user => (
          <div key={user.id} className="user-card">
            <div>
              <strong>{user.name}</strong>
              <br />
              <span>{user.email}</span>
            </div>
            <button onClick={() => deleteUser(user.id)} className="delete-btn">
              Delete
            </button>
          </div>
        ))}
      </div>
    </div>
  );
}

src/styles.css

* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family: -apple-system, BlinkMacSystemFont, sans-serif;
  background: #f5f5f5;
  color: #333;
}

.container {
  max-width: 800px;
  margin: 0 auto;
  padding: 2rem;
}

h1 {
  color: #2563eb;
  margin-bottom: 2rem;
}

.form {
  background: white;
  padding: 1.5rem;
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
  margin-bottom: 2rem;
  display: flex;
  gap: 1rem;
  flex-wrap: wrap;
}

.form input {
  flex: 1;
  min-width: 200px;
  padding: 0.75rem;
  border: 1px solid #ddd;
  border-radius: 4px;
}

.form button {
  padding: 0.75rem 1.5rem;
  background: #2563eb;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.form button:hover {
  background: #1d4ed8;
}

.form button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
}

.users {
  background: white;
  padding: 1.5rem;
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

.user-card {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: 1rem;
  border-bottom: 1px solid #eee;
}

.user-card:last-child {
  border-bottom: none;
}

.delete-btn {
  padding: 0.5rem 1rem;
  background: #dc2626;
  color: white;
  border: none;
  border-radius: 4px;
  cursor: pointer;
}

.delete-btn:hover {
  background: #b91c1c;
}

Best Practices#

Project Structure#

my-app/
├── src/
│   ├── components/
│   │   ├── Header.tsx
│   │   └── UserList.tsx
│   ├── styles/
│   │   ├── globals.css
│   │   └── components.css
│   ├── utils/
│   │   └── api.ts
│   ├── App.tsx
│   └── main.tsx
├── public/
│   ├── index.html
│   ├── dashboard.html
│   └── favicon.ico
├── server/
│   ├── routes/
│   │   ├── users.ts
│   │   └── auth.ts
│   ├── db/
│   │   └── schema.sql
│   └── index.ts
├── bunfig.toml
└── package.json

Environment-Based Configuration#

server/config.ts

export const config = {
  development: process.env.NODE_ENV !== "production",
  port: process.env.PORT || 3000,
  database: {
    url: process.env.DATABASE_URL || "./dev.db",
  },
  cors: {
    origin: process.env.CORS_ORIGIN || "*",
  },
};

Error Handling#

server/middleware.ts

export function errorHandler(error: Error, req: Request) {
  console.error("Server error:", error);

  if (process.env.NODE_ENV === "production") {
    return Response.json({ error: "Internal server error" }, { status: 500 });
  }

  return Response.json(
    {
      error: error.message,
      stack: error.stack,
    },
    { status: 500 },
  );
}

API Response Helpers#

server/utils.ts

export function json(data: any, status = 200) {
  return Response.json(data, { status });
}

export function error(message: string, status = 400) {
  return Response.json({ error: message }, { status });
}

export function notFound(message = "Not found") {
  return error(message, 404);
}

export function unauthorized(message = "Unauthorized") {
  return error(message, 401);
}

Type Safety#

types/api.ts

export interface User {
  id: number;
  name: string;
  email: string;
  created_at: string;
}

export interface CreateUserRequest {
  name: string;
  email: string;
}

export interface ApiResponse<T> {
  data?: T;
  error?: string;
}

Deployment#

Production Build#

terminal

# Build for production
bun build --target=bun --production --outdir=dist ./server/index.ts

# Run production server
NODE_ENV=production bun dist/index.js

Docker Deployment#

Dockerfile

FROM oven/bun:1 as base
WORKDIR /usr/src/app

# Install dependencies
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile

# Copy source code
COPY . .

# Build application
RUN bun build --target=bun --production --outdir=dist ./server/index.ts

# Production stage
FROM oven/bun:1-slim
WORKDIR /usr/src/app
COPY --from=base /usr/src/app/dist ./
COPY --from=base /usr/src/app/public ./public

EXPOSE 3000
CMD ["bun", "index.js"]

Environment Variables#

.env.production

NODE_ENV=production
PORT=3000
DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
CORS_ORIGIN=https://myapp.com

Migration from Other Frameworks#

From Express + Webpack#

server.ts

// Before (Express + Webpack)
app.use(express.static("dist"));
app.get("/api/users", (req, res) => {
  res.json(users);
});

// After (Bun fullstack)
serve({
  routes: {
    "/": homepage, // Replaces express.static
    "/api/users": {
      GET() {
        return Response.json(users);
      },
    },
  },
});

From Next.js API Routes#

server.ts

// Before (Next.js)
export default function handler(req, res) {
  if (req.method === 'GET') {
    res.json(users);
  }
}

// After (Bun)
"/api/users": {
  GET() { return Response.json(users); }
}

Limitations and Future Plans#

Current Limitations#

Auto-discovery of API routes is not implemented
Server-side rendering (SSR) is not built-in

Planned Features#

File-based routing for API endpoints
Built-in SSR support
Enhanced plugin ecosystem

The fullstack dev server is a work in progress. Features and APIs may change.