O Bun suporta dois tipos de recarregamento automático via flags de CLI:

• Modo --watch, que reinicia rigidamente o processo do Bun quando arquivos importados mudam.
• Modo --hot, que recarrega suavemente o código (sem reiniciar o processo) quando arquivos importados mudam.

---

Modo --watch

O modo watch pode ser usado com bun test ou ao executar arquivos TypeScript, JSX e JavaScript.

Para executar um arquivo em modo --watch:

bun --watch index.tsx

Para executar seus testes em modo --watch:

bun --watch test

No modo --watch, o Bun mantém controle de todos os arquivos importados e os observa em busca de mudanças. Quando uma mudança é detectada, o Bun reinicia o processo, preservando o mesmo conjunto de argumentos de CLI e variáveis de ambiente usados na execução inicial. Se o Bun quebrar, --watch tentará reiniciar automaticamente o processo.

NOTE

⚡️ Recarregamentos são rápidos. Os watchers de filesystem que você provavelmente está acostumado têm várias camadas de bibliotecas envolvendo as APIs nativas ou pior, dependem de polling.

Em vez disso, o Bun usa APIs nativas de watcher de filesystem do sistema operacional como kqueue ou inotify para detectar mudanças em arquivos. O Bun também faz várias otimizações para permitir que escale para projetos maiores (como definir um rlimit alto para file descriptors, buffers de caminho de arquivo estaticamente alocados, reutilizar file descriptors quando possível, etc).

Os exemplos a seguir mostram o Bun recarregando ao vivo um arquivo enquanto é editado, com VSCode configurado para salvar o arquivo a cada tecla pressionada.

bun run --watch watchy.tsx

watchy.tsx

import { serve } from "bun";

console.log("I restarted at:", Date.now());

serve({
  port: 4003,
  fetch(request) {
    return new Response("Sup");
  },
});

Neste exemplo, o Bun está

Executando bun test em modo watch e save-on-keypress habilitado:

bun --watch test

NOTE

A flag **`--no-clear-screen`** é útil em cenários onde você não quer que o terminal seja limpo, como quando executa múltiplos comandos `bun build --watch` simultaneamente usando ferramentas como `concurrently`. Sem esta flag, a saída de uma instância poderia limpar a saída de outras, potencialmente escondendo erros de uma instância beneath a saída de outra. A flag `--no-clear-screen`, similar ao `--preserveWatchOutput` do TypeScript, previne este problema. Ela pode ser usada em combinação com `--watch`, por exemplo: `bun build --watch --no-clear-screen`.

---

Modo --hot

Use bun --hot para habilitar hot reloading ao executar código com Bun. Isto é distinto do modo --watch em que o Bun não reinicia rigidamente todo o processo. Em vez disso, ele detecta mudanças de código e atualiza seu cache interno de módulos com o novo código.

NOTE

Isto não é o mesmo que hot reloading no browser! Muitas bibliotecas fornecem uma experiência de "hot reloading", onde você pode editar e salvar seu código frontend (digamos, um componente React) e ver as mudanças refletidas no browser sem recarregar a página. O `--hot` do Bun é o equivalente server-side desta experiência. Para obter hot reloading no browser, use um framework como [Vite](https://vite.dev).

bun --hot server.ts

Começando do entrypoint (server.ts no exemplo acima), o Bun constrói um registro de todos os arquivos fonte importados (excluindo aqueles em node_modules) e os observa em busca de mudanças. Quando uma mudança é detectada, o Bun executa um "soft reload". Todos os arquivos são reavaliados, mas todo estado global (notavelmente, o objeto globalThis) é persistido.

server.ts

// make TypeScript happy
declare global {
  var count: number;
}

globalThis.count ??= 0;
console.log(`Reloaded ${globalThis.count} times`);
globalThis.count++;

// prevent `bun run` from exiting
setInterval(function () {}, 1000000);

Se você executar este arquivo com bun --hot server.ts, você verá a contagem de recarregamento incrementar toda vez que salvar o arquivo.

bun --hot index.ts

Reloaded 1 times
Reloaded 2 times
Reloaded 3 times

Watchers de arquivo tradicionais como nodemon reiniciam todo o processo, então servidores HTTP e outros objetos stateful são perdidos. Em contraste, bun --hot é capaz de refletir o código atualizado sem reiniciar o processo.

Servidores HTTP

Isto torna possível, por exemplo, atualizar seu handler de requisição HTTP sem desligar o servidor em si. Quando você salva o arquivo, seu servidor HTTP será recarregado com o código atualizado sem o processo ser reiniciado. Isto resulta em velocidades de refresh seriamente rápidas.

server.ts

globalThis.count ??= 0;
globalThis.count++;

Bun.serve({
  fetch(req: Request) {
    return new Response(`Reloaded ${globalThis.count} times`);
  },
  port: 3000,
});

NOTE

**Nota** — Em uma versão futura do Bun, suporte para `import.meta.hot` do Vite é planejado para habilitar melhor gerenciamento de lifecycle para hot reloading e alinhar com o ecosystem.

Detalhes de implementação">

No hot reload, o Bun:

• Reseta o cache interno require e registro de módulos ES (Loader.registry)
• Executa o garbage collector sincronamente (para minimizar memory leaks, ao custo de performance de runtime)
• Re-transpila todo seu código do zero (incluindo sourcemaps)
• Re-avalia o código com JavaScriptCore

Esta implementação não é particularmente otimizada. Ela re-transpila arquivos que não mudaram. Não faz nenhuma tentativa de compilação incremental. É um ponto de partida.