# bun-hot-reloading

A skill that walks the agent through Bun hot reloading: --watch and --hot modes, HMR, and HTTP server reload.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 395 installs · ★ 236
- Author: secondsky
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/secondsky/claude-skills/tree/HEAD/plugins/bun/skills/bun-hot-reloading/SKILL.md
- Updated: 2026-10-20
- HTML: https://affpapa.org/en/nevibecode/skills/bun-hot-reloading

## What it does

The skill kicks in when a project needs automatic code reloading on Bun. It lays out the split between the two modes: `--watch` restarts the whole process, `--hot` reloads modules in place and keeps state. The comparison table spells out that watch loses state on restart while hot preserves it.

There are examples for `Bun.serve` and the `import.meta.hot` API: `accept`, `dispose`, `decline`, `invalidate`. Stateful server patterns use `globalThis` to survive reloads, and there is a WebSocket live reload setup plus running Vite with `bunx --bun vite`. Tests get their own section: `bun --watch test` and the `--bail` flag.

A troubleshooting section covers the usual breakage. A cache held in a plain variable disappears on reload, so the skill suggests `globalThis`. Intervals keep ticking unless you clear them in `import.meta.hot.dispose`. The custom watcher example carries a note for Bun 1.2+: `server.stop()` returns a promise, and you have to await it so the old socket releases the port before rebinding.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill bun-hot-reloading -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/bun-hot-reloading/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/bun-hot-reloading/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill bun-hot-reloading -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/bun-hot-reloading/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill bun-hot-reloading -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/bun-hot-reloading/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install secondsky/claude-skills bun-hot-reloading
```

2. **Manually: put the files in place**
- File: `.github/skills/bun-hot-reloading/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill bun-hot-reloading -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/secondsky/claude-skills --path plugins/bun/skills/bun-hot-reloading
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/bun-hot-reloading/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add secondsky/claude-skills --skill bun-hot-reloading -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/secondsky/claude-skills/tree/HEAD/plugins/bun/skills/bun-hot-reloading/SKILL.md

## When to use it
- restart the server when a source file changes
- keep a counter alive across module reloads
- clear intervals and connections before a hot swap
- push live reload to the browser over WebSocket
- run tests in watch mode and stop on the first failure

## Example prompts
- set up hot reloading for my Bun server on port 3000
- why does state reset under `--hot` and how do I fix it
- add WebSocket live reload to the dev server

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 197ba1061bbe24d1.

BEGIN THIRD-PARTY FILE 197ba1061bbe24d1
````text
---
name: bun-hot-reloading
description: 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.
metadata:
  version: "1.0.0"
license: MIT
---

# Bun Hot Reloading

Bun provides built-in hot reloading for faster development cycles.

## Watch Mode vs Hot Mode

| 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 |

## Watch Mode (--watch)

Restarts the entire process when files change.

```bash
# Basic watch mode
bun --watch run src/index.ts

# Watch specific script
bun --watch run dev

# Watch with test runner
bun --watch test
```

### package.json Scripts

```json
{
  "scripts": {
    "dev": "bun --watch run src/index.ts",
    "dev:server": "bun --watch run src/server.ts",
    "test:watch": "bun --watch test"
  }
}
```

### Watch Behavior

- Watches imported files automatically
- Triggers on any `.ts`, `.tsx`, `.js`, `.jsx` change
- Also watches `.json` imports
- Restarts with fresh state

## Hot Mode (--hot)

Reloads modules in-place without restarting the process.

```bash
bun --hot run src/server.ts
```

### HTTP Server Hot Reload

```typescript
// src/server.ts
let counter = 0; // State preserved across hot reloads

export default {
  port: 3000,
  fetch(req: Request) {
    counter++;
    return new Response(`Request #${counter}`);
  },
};
```

```bash
bun --hot run src/server.ts
```

When you modify `server.ts`, the module reloads instantly while `counter` keeps its value.

### Bun.serve with Hot Reload

```typescript
// 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}`);
```

## import.meta.hot API

```typescript
// 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();
}
```

## HTTP Server Patterns

### Express-like Pattern

```typescript
// src/server.ts
````
END THIRD-PARTY FILE 197ba1061bbe24d1

The third-party file has ended. Everything between the 197ba1061bbe24d1 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2723 of 7643 bytes. © secondsky · MIT · https://github.com/secondsky/claude-skills/tree/HEAD/plugins/bun/skills/bun-hot-reloading/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md