Dev Server#

Name: Buntok Framework
Author: Buntok

Bun development server with HMR (Hot Module Replacement) enabled. Thin wrapper around Bun.serve() with development: true - automatic re-bundling, source maps, and hot reload when files change.

Import#

typescript

import { devServer } from "@buntok/core/dev";

Usage#

Minimal - default returns 404#

typescript

import { devServer } from "@buntok/core/dev";

devServer({
  port: 3000,
  onReady: (info) => console.log(`Dev server: http://localhost:${info.port}`),
});

With routes - serve HTML files#

typescript

import { devServer } from "@buntok/core/dev";
import homepage from "./index.html";

devServer({
  port: 3000,
  routes: { "/": homepage },
  onReady: (info) => console.log(`Dev server: http://localhost:${info.port}`),
});

With custom fetch handler#

typescript

import { devServer } from "@buntok/core/dev";

devServer({
  port: 3000,
  fetch: (req) => new Response(`Hello from ${req.url}`),
});

Options#

Option	Type	Default	Description
port	number	3000	Port to listen on. `0` = random available port
hostname	string	"localhost"	Hostname to bind to
routes	Record<string, unknown>	-	Bun routes object - maps paths to HTML files or handlers
fetch	(req: Request) => Response	404 handler	Custom fetch handler - used when no routes provided
hmr	boolean	true	Enable Hot Module Replacement
console	boolean	true	Echo browser console to terminal
onReady	(info) => void	-	Called when server starts
...rest	BunServeOptions	-	Any additional Bun.serve() options

When to Use#

Web/frontend development - HMR for HTML, CSS, JS changes
Full-stack apps - serve templates + API routes simultaneously
Framework development - test BunTok itself with hot reload

When NOT to Use#

Pure API servers - bun --watch server.ts is simpler and sufficient
Vercel deployment - Vercel handles serving; use app.fetch() instead
Production - always use bun run build + bun run start

Return Value#

Returns the Bun.serve() instance:

typescript

const server = devServer({ port: 0 });
console.log(server.port); // actual port (useful with port: 0)
server.stop(); // stop the server

Info

devServer() without routes or fetch returns 404 for all requests by default. This is useful for testing that the server starts correctly.

CLI Dev Command#

The buntok dev CLI command provides a convenient way to start your development server with hot reload:

typescript

bunx buntok dev

Public Tunnel#

Use --expose to create a public URL via localtunnel. Useful for webhook testing, mobile testing, or sharing with others:

typescript

bunx buntok dev --expose

typescript

$ bunx buntok dev --expose

Starting development server with tunnel...

  Server running at http://localhost:1212
  Tunnel: https://buntok-1234.loca.lt → http://localhost:1212

  Press Ctrl+C to stop

Warning

Requires localtunnel as a dev dependency. Install with: bun add -d localtunnel

Options#

Flag	Description
`--expose`	Create public tunnel URL via localtunnel
`--port=PORT`	Port number (default: 1212)

Auto-restart on .env changes

buntok dev also watches .env, .env.development, and .env.local. When any of them changes, the server restarts automatically with the fresh values - Bun's own --watch ignores .env files, so no manual restart is needed after editing environment variables.

PreviousPlugins Next Logger