Use when implementing hot reloading with Bun (--hot, --watch), HMR, or automatic code reloading during development. Covers watch mode, hot mode, and HTTP server reload.
Provides Bun hot reloading patterns with `--watch` and `--hot` flags, including HTTP server reload, `import.meta.hot` API, and state preservation techniques.
/plugin marketplace add secondsky/claude-skills/plugin install bun@claude-skillsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Bun provides built-in hot reloading for faster development cycles.
| Feature | --watch | --hot |
|---|---|---|
| Behavior | Restart process | Reload modules |
| State | Lost on reload | Preserved |
| Speed | ~20ms restart | Instant reload |
| Use case | Any file type | Bun.serve HTTP |
Restarts the entire process when files change.
# Basic watch mode
bun --watch run src/index.ts
# Watch specific script
bun --watch run dev
# Watch with test runner
bun --watch test
{
"scripts": {
"dev": "bun --watch run src/index.ts",
"dev:server": "bun --watch run src/server.ts",
"test:watch": "bun --watch test"
}
}
.ts, .tsx, .js, .jsx change.json importsReloads modules in-place without restarting the process.
bun --hot run src/server.ts
// src/server.ts
let counter = 0; // State preserved across hot reloads
export default {
port: 3000,
fetch(req: Request) {
counter++;
return new Response(`Request #${counter}`);
},
};
bun --hot run src/server.ts
When you modify server.ts, the module reloads instantly while counter keeps its value.
// src/server.ts
const server = Bun.serve({
port: 3000,
fetch(req) {
return new Response("Hello!");
},
});
// Hot reload handler
if (import.meta.hot) {
import.meta.hot.accept(() => {
console.log("Hot reload!");
});
}
console.log(`Server running on port ${server.port}`);
// Check if hot reload is available
if (import.meta.hot) {
// Accept updates to this module
import.meta.hot.accept();
// Accept with callback
import.meta.hot.accept((newModule) => {
console.log("Module updated:", newModule);
});
// Cleanup before reload
import.meta.hot.dispose(() => {
// Close connections, clear intervals, etc.
clearInterval(myInterval);
});
// Decline hot reload (force full restart)
import.meta.hot.decline();
// Invalidate this module (trigger parent reload)
import.meta.hot.invalidate();
}
// src/server.ts
import { createApp } from "./app";
const app = createApp();
const server = Bun.serve({
port: 3000,
fetch: app.fetch,
});
// Hot reload: recreate app
if (import.meta.hot) {
import.meta.hot.accept((newModule) => {
// Reload with new fetch handler
server.reload({
fetch: newModule.default.fetch,
});
});
}
// src/server.ts
// Store in globalThis to survive reloads
globalThis.connections ??= new Set();
const server = Bun.serve({
port: 3000,
fetch(req) {
return new Response(`Connections: ${globalThis.connections.size}`);
},
websocket: {
open(ws) {
globalThis.connections.add(ws);
},
close(ws) {
globalThis.connections.delete(ws);
},
},
});
if (import.meta.hot) {
import.meta.hot.accept();
}
// dev-server.ts
import { watch } from "fs";
const srcDir = "./src";
let server: ReturnType<typeof Bun.serve> | null = null;
async function startServer() {
// Dynamic import with cache busting
const module = await import(`./src/server.ts?t=${Date.now()}`);
if (server) {
server.stop();
}
server = Bun.serve(module.default);
console.log(`Server started on port ${server.port}`);
}
// Initial start
await startServer();
// Watch for changes
watch(srcDir, { recursive: true }, async (event, filename) => {
if (filename?.endsWith(".ts") || filename?.endsWith(".tsx")) {
console.log(`\n[${event}] ${filename}`);
await startServer();
}
});
console.log("Watching for changes...");
// src/dev-server.ts
const clients = new Set<ServerWebSocket>();
const server = Bun.serve({
port: 3000,
fetch(req, server) {
if (req.headers.get("upgrade") === "websocket") {
server.upgrade(req);
return;
}
// Inject reload script in dev
const html = `
<!DOCTYPE html>
<html>
<body>
<h1>Hello!</h1>
<script>
const ws = new WebSocket('ws://localhost:3000');
ws.onmessage = (e) => {
if (e.data === 'reload') location.reload();
};
</script>
</body>
</html>
`;
return new Response(html, {
headers: { "Content-Type": "text/html" },
});
},
websocket: {
open(ws) {
clients.add(ws);
},
close(ws) {
clients.delete(ws);
},
},
});
// Notify clients on file change
watch("./src", { recursive: true }, () => {
clients.forEach((ws) => ws.send("reload"));
});
For frontend development with HMR:
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
export default defineConfig({
plugins: [react()],
server: {
port: 5173,
hmr: true,
},
});
# Use Bun to run Vite
bunx --bun vite
# Watch tests
bun --watch test
# Watch specific file
bun --watch test src/utils.test.ts
# With bail (stop on first failure)
bun --watch test --bail
// Check if running with --hot
const isHot = !!import.meta.hot;
// Check if running with --watch
const isWatch = process.env.BUN_WATCH === "1";
// Development mode
const isDev = process.env.NODE_ENV !== "production";
if (isDev) {
console.log("Running in development mode");
console.log(`Hot reload: ${isHot}`);
console.log(`Watch mode: ${isWatch}`);
}
// ❌ State lost on hot reload
let cache = new Map();
// ✅ State preserved on hot reload
globalThis.cache ??= new Map();
const cache = globalThis.cache;
// ❌ Interval keeps running after reload
setInterval(() => console.log("tick"), 1000);
// ✅ Clean up on dispose
const interval = setInterval(() => console.log("tick"), 1000);
if (import.meta.hot) {
import.meta.hot.dispose(() => {
clearInterval(interval);
});
}
// ❌ Import not watched
const config = require("./config.json");
// ✅ Use import for watching
import config from "./config.json";
| Error | Cause | Fix |
|---|---|---|
Changes not detected | File not imported | Check import chain |
State lost | Using --watch | Use --hot or globalThis |
Port in use | Server not stopped | Implement server.stop() |
Memory leak | No cleanup | Use dispose callback |
Load references/advanced-hmr.md when:
Load references/debugging.md when:
Use when working with Payload CMS projects (payload.config.ts, collections, fields, hooks, access control, Payload API). Use when debugging validation errors, security issues, relationship queries, transactions, or hook behavior.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.