Hot Reload: recarga a quente e como acelera o desenvolvimento

O que é Hot Reload?

Hot Reload é um mecanismo de desenvolvimento onde as alterações nos arquivos de origem são imediatamente refletidas em um aplicativo em execução sem reiniciá-lo. O desenvolvedor edita o código no editor, salva o arquivo e o resultado fica instantaneamente visível no navegador ou emulador.

A principal característica desta tecnologia é a preservação do estado do aplicativo. Variáveis na memória, dados em formulários, navegação atual — tudo permanece no lugar. O desenvolvedor não precisa repetir uma sequência de ações para retornar à tela necessária.

No desenvolvimento web, o Hot Reload é implementado através do mecanismo Hot Module Replacement (HMR). O bundler monitora as alterações nos arquivos, determina quais módulos são afetados e envia o código atualizado para o navegador via WebSocket. O navegador substitui apenas esses módulos sem recarregar a página.

A popularidade do Hot Reload disparou com o crescimento dos aplicativos de página única (SPA), onde um recarregamento completo da página destrói todo o estado do aplicativo cliente. React, Vue, Angular e outros frameworks recomendam HMR como modo principal de desenvolvimento.

Como o HMR funciona dentro do bundler

O mecanismo HMR consiste em quatro estágios. O bundler no lado do servidor compila o módulo alterado, gera um patch JSON com a nova versão do código e o envia ao navegador através de uma conexão WebSocket. O runtime HMR do lado do navegador recebe o patch, substitui o módulo antigo pelo novo e notifica os assinantes do módulo.

Estágio de compilação e envio

O Webpack Dev Server usa WebSocket para se comunicar com o cliente. Quando um arquivo muda, o bundler gera hot-update.js e hot-update.json com um manifesto das alterações. O cliente carrega automaticamente esses arquivos via JSONP.

// webpack.config.js - configuração HMR
const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  mode: 'development',
  devServer: {
    hot: true,
    liveReload: false
  },
  plugins: [new HtmlWebpackPlugin()]
};

Aplicação do módulo no cliente

O runtime HMR no navegador verifica se o módulo sendo substituído suporta accept. Se o módulo declarou module.hot.accept(), o runtime o substitui in-place e executa o callback de atualização. Se accept não for declarado, o HMR cai para o nível do módulo pai.

No React Fast Refresh, essa lógica está integrada ao nível do framework — não é necessário escrever manualmente module.hot.accept em cada arquivo. O plugin Babel react-refresh/babel adiciona código que substitui componentes com segurança sem perder o estado.

Diferença entre Hot Reload, Live Reload e Full Reload

Esses três termos são frequentemente confundidos, mas diferem radicalmente em comportamento. Live Reload recarrega a página inteira a qualquer alteração — todo o estado é perdido. Full Reload ocorre quando o servidor de desenvolvimento é reiniciado completamente, perdendo não apenas o estado do cliente, mas também do servidor.

A escolha entre Hot e Live afeta diretamente a velocidade de desenvolvimento. Com HMR, o ciclo “editar código → ver resultado” leva 50-200 ms. Com Live Reload — 1-3 segundos mais tempo de restauração de contexto. Ao longo de um dia de trabalho, a diferença chega a dezenas de minutos de tempo economizado.

React Fast Refresh: recursos para React

React Fast Refresh é a implementação oficial do Hot Reload otimizada para componentes React. Ele substituiu o antigo mecanismo React Hot Loader, que era instável e exigia configuração manual. Fast Refresh está integrado ao Create React App, Next.js, Vite e Webpack através do react-refresh/babel.

Suporte a componentes funcionais

Fast Refresh preserva corretamente o estado dos componentes funcionais quando seu código muda. Se você alterar apenas a marcação JSX, useState e outros hooks mantêm seus valores. Se a lógica do hook mudar, o componente é remontado.

// Exemplo - estado preservado quando JSX muda
import React, { useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0);

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

Regras de substituição segura

Fast Refresh não preserva o estado se o novo código contiver um erro de compilação. Se o componente não for exportado por padrão (named export), o estado também pode não ser preservado. Recomenda-se usar export default para componentes e envolver exportações em memo se for necessário garantir a preservação do estado.

Ferramentas de build com suporte a HMR

Bundlers modernos fornecem HMR. Webpack é o pioneiro em HMR com configuração flexível via devServer.hot. Vite usa ESM nativo e esbuild para HMR instantâneo sem bundling. Parcel oferece HMR zero-config. Turbopack é um novo bundler da Vercel com HMR baseado em Rust.

Vite se destaca em velocidade — HMR no Vite funciona através de módulos ES nativos do navegador. Quando um arquivo muda, o Vite envia apenas esse módulo via import(), sem recompilar o projeto inteiro. O Webpack compila cada módulo inteiramente, o que desacelera o HMR em projetos grandes.

Exemplos de configuração HMR em projetos

Vamos ver a configuração de HMR para diferentes bundlers. No Webpack, é necessário definir hot: true no devServer e adicionar react-refresh/babel. No Vite, HMR funciona integrado com qualquer preset. No Next.js, Fast Refresh está habilitado por padrão através do turbocompilador.

Vite com React

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    hmr: {
      port: 3001
    }
  }
});

Webpack 5 com Fast Refresh

// webpack.config.js
const ReactRefreshWebpackPlugin =
  require('@pmmmwh/react-refresh-webpack-plugin');

module.exports = {
  mode: 'development',
  devServer: { hot: true },
  plugins: [new ReactRefreshWebpackPlugin()],
  module: {
    rules: [
      {
        test: /\.jsx?$/u,
        use: 'babel-loader'
      }
    ]
  }
};

Limitações e problemas da recarga a quente

HMR não funciona corretamente em todos os cenários. Módulos CSS com classes dinâmicas podem não ser aplicados. Variáveis globais e singletons (store Redux, roteador) podem reiniciar ao recarregar. Bibliotecas pesadas com HMR às vezes podem gerar vazamentos de memória devido à substituição de módulos sem GC.

A solução para problemas de HMR é isolar o código quente em componentes puros sem efeitos colaterais. Efeitos colaterais (assinaturas WebSocket, temporizadores) devem ser limpos no useEffect. Para Redux, recomenda-se um persister que salve o estado no sessionStorage. Soluções CSS como CSS Modules ou styled-components funcionam corretamente com HMR sem configuração adicional.

Outra limitação é a depuração em produção: HMR é intencionalmente desativado em builds de produção. O código-fonte é minificado e a substituição a quente em produção é impossível. Para depurar erros em produção, use source maps e logging, mas não HMR.