Qué es el HMR: actualizar módulos sin recargar ni perder el estado

Editas el color de un botón dentro de un formulario a medio rellenar, con un modal abierto y el scroll a mitad de página. Guardas. El botón cambia y todo lo demás sigue exactamente donde estaba: el formulario con sus datos, el modal abierto, el scroll intacto. Eso es el HMR, y una vez lo interiorizas cuesta volver a programar sin él. No es un truco de comodidad: es un cambio en la naturaleza del bucle entre escribir código y ver su efecto.

Del full reload al reemplazo en caliente

Hay tres niveles de inmediatez entre guardar un archivo y ver el cambio, y confundirlos es la fuente de casi todos los malentendidos sobre el HMR.

• Recarga manual. Editas, cambias a la ventana del navegador y pulsas refrescar. La página se reconstruye desde cero.
• Live reload. Un observador de archivos detecta el cambio y dispara por ti un location.reload(). Es más rápido de disparar, pero igual de destructivo: la página reinicia, todo el grafo de módulos se reejecuta desde el punto de entrada y todo el estado en memoria muere.
• HMR. El dev server envía a la página en marcha solo el módulo que cambió; el runtime lo intercambia en su sitio mientras el resto de la aplicación sigue corriendo, intacta, con su estado vivo.

La diferencia esencial no es la velocidad: es que el live reload destruye el runtime y el HMR lo preserva. Una recarga completa reejecuta tu grafo entero desde el entry; el HMR reejecuta un módulo.

Conviene ver el live reload no como una versión más lenta del HMR, sino como su opuesto conceptual. El live reload trata tu aplicación como un documento que se vuelve a pedir entero; el HMR la trata como un proceso vivo al que se le cambian piezas por dentro. La primera es la metáfora del navegador de los noventa —pedir una página y renderizarla—; la segunda es la metáfora de un sistema en ejecución que se parchea sin apagarlo, más cercana a cómo se actualiza el software de una centralita o de un satélite que a cómo se recarga un sitio web.

flowchart LR
edit[Editas un modulo] --> watch[El dev server detecta el cambio]
watch --> reload[Live reload recarga toda la pagina]
watch --> hmr[HMR envia solo el modulo cambiado]
reload --> dead[Estado destruido y grafo reejecutado]
hmr --> alive[Estado vivo y solo un modulo reejecutado]
style dead fill:#f38ba8,color:#11111b
style alive fill:#a6e3a1,color:#11111b

El estado que no quieres perder

Al trabajar, el estado de la interfaz se acumula: un asistente en el paso 4, una tabla filtrada y ordenada, un lienzo con un dibujo a medias, un chat desplazado hasta cierto mensaje, una sesión autenticada, una ruta anidada muy adentro de la app. Para reproducir ese estado tras una recarga completa tienes que reconstruirlo a mano, clic a clic, en cada iteración. Ese es el impuesto real: no los milisegundos de la recarga, sino la reconstrucción manual del contexto antes de cada intento. El HMR lo elimina: te quedas exactamente en el estado donde vive el bug y iteras sobre él directamente.

Hay también un ángulo cognitivo. El bucle interno —editar, ver, ajustar— es donde un desarrollador pasa la mayoría de sus horas. Cuando ese bucle es de menos de un segundo y no destruye nada, permaneces en flujo: el código se siente como un material vivo que moldeas, no como un programa que reinicias sin cesar. Cuando cada iteración cuesta una recarga más una reconstrucción, la atención se rompe una y otra vez. El HMR convierte la página en un medio que responde.

Esta es la razón por la que el HMR se volvió una expectativa y no un lujo: una vez que el bucle interno es instantáneo y no destructivo, cualquier herramienta que te obligue a reconstruir el contexto en cada cambio se siente rota, aunque hace diez años fuera lo normal. El listón subió, y subió para siempre.

Tres piezas: servidor, canal, runtime

El HMR es un protocolo distribuido entre el dev server y la página en marcha. Tres piezas lo sostienen.

• Servidor. Vigila el sistema de archivos, mantiene el grafo de módulos, calcula a qué módulos afecta una edición y empuja una actualización. En Vite 8 el grafo y el HMR son por entorno gracias a la Environment API: cliente, SSR en Node y edge tienen cada uno su grafo y su canal.
• Canal. Un transporte, casi siempre un WebSocket que abre el cliente. El servidor manda cargas de actualización —js-update, css-update, full-reload, prune— y el cliente también puede responder.
• Runtime. El módulo @vite/client, inyectado en la página, recibe las cargas, vuelve a importar la nueva versión del módulo con una marca de tiempo fresca e invoca los callbacks que ese módulo registró con import.meta.hot.

El baile entre las tres piezas ocurre en milisegundos y sigue siempre la misma coreografía: el servidor detecta el cambio, recalcula el conjunto de módulos afectados y envía por el canal una carga que nombra qué actualizar y con qué marca de tiempo. El runtime importa dinámicamente cada módulo nombrado usando esa marca como parámetro de consulta —así el navegador no sirve la versión cacheada— y ejecuta los callbacks de aceptación. Ni el servidor sabe qué hará el cliente con el módulo, ni el cliente sabe cómo lo calculó el servidor: el canal es la única frontera, y esa separación es la que deja funcionar al HMR igual con cualquier framework encima.

// forma de una carga de actualizacion que el servidor envia por el canal
{
  type: "update",
  updates: [
    { type: "js-update", path: "/src/Boton.tsx", timestamp: 1730000000 }
  ]
}

// import.meta.hot solo existe en desarrollo; en el build es undefined
if (import.meta.hot) {
  import.meta.hot.accept((nuevo) => {
    // aplica la nueva version sin recargar la pagina
    render(nuevo.estado);
  });
}

Configurar y observar el canal

El canal es un WebSocket, y como todo WebSocket puede fallar al conectarse cuando hay un proxy inverso, HTTPS, un túnel o un contenedor de por medio. Por eso Vite expone server.hmr para ajustar cómo el cliente encuentra al servidor: el puerto que anunciar al navegador, el host, el protocolo o la ruta del socket. El síntoma de una mala configuración es inconfundible: guardas y no pasa nada, o el navegador reconecta en bucle sin aplicar cambios.

// vite.config.ts: ajustar el canal cuando el HMR corre tras un proxy
import { defineConfig } from "vite";

export default defineConfig({
  server: {
    hmr: {
      overlay: true,       // errores a pantalla completa sobre la app
      clientPort: 443,     // el puerto que ve el navegador, no el interno
      protocol: "wss",     // WebSocket seguro tras un proxy TLS
    },
  },
});

Este ajuste importa más de lo que parece en cuanto sales de localhost. Si pruebas la app desde el móvil en tu red local, desde un contenedor Docker o a través de un túnel público, el navegador vive en un host distinto del que Vite cree, y el WebSocket apunta al sitio equivocado. Alinear host y clientPort con la dirección que realmente ve el navegador es lo que restaura el HMR en esos escenarios, y una de las causas más comunes de ese HMR que funciona en tu máquina pero no en la del compañero.

El runtime también emite eventos que puedes escuchar para instrumentar el propio HMR. import.meta.hot.on("vite:beforeUpdate", ...) se dispara antes de aplicar una actualización, vite:afterUpdate después, vite:beforeFullReload justo antes de una recarga completa, y vite:ws:disconnect cuando se cae el canal. Enganchar estos eventos es la forma de depurar por qué una actualización no llega o por qué la página recarga cuando esperabas un cambio local.