Integrar con el tooling moderno: Vite o webpack, recarga en caliente y convivencia con TypeScript

Hay una tentación comprensible al adoptar un lenguaje que trae su propio compilador y su propio gestor de paquetes, y es tratarlo como una isla: una carpeta aparte, un comando aparte, un artefacto que se copia al final. Funciona, y durante un tiempo parece limpio. Lo que se pierde por el camino es todo aquello que el resto del equipo da por supuesto: que al guardar un archivo el navegador refleje el cambio en menos de un segundo, que las hojas de estilo y las imágenes pasen por el mismo proceso, que la salida lleve huella de contenido en el nombre, que el editor señale un error de tipos en la frontera entre los dos lenguajes. Integrar Elm en un empaquetador moderno no es una comodidad opcional sino la diferencia entre una tecnología que el equipo adopta y una que tolera. La buena noticia es que la integración es sorprendentemente sencilla, porque el compilador de Elm hace una sola cosa y la hace de forma predecible. La menos buena es que el borde entre los dos sistemas de tipos sigue siendo un borde, y ninguna herramienta lo cierra del todo.

El compilador como un nodo más del grafo

La integración se apoya en una idea simple: hacer que importar un archivo fuente de Elm desde el código anfitrión sea una importación normal, y que el complemento del empaquetador se encargue de invocar al compilador y devolver el módulo resultante. Lo que se obtiene de esa importación es un objeto con un constructor por cada programa compilado, y ese constructor recibe el nodo del documento donde montar y las banderas de arranque. A partir de ahí todo el resto de la maquinaria del empaquetador funciona sin saber que hay otro lenguaje debajo: la salida entra en la división de paquetes, recibe su huella de contenido en el nombre, participa en la sustitución de variables de entorno y se sirve por el mismo servidor de desarrollo.

import { defineConfig } from "vite";
import elm from "vite-plugin-elm";

export default defineConfig({
  plugins: [
    elm({ debug: true, optimize: false }),
  ],
  build: { target: "es2018" },
});

Hay un detalle que conviene tener presente porque desconcierta a quien viene de otros lenguajes: la unidad de compilación de Elm no es el archivo sino el programa completo alcanzable desde el punto de entrada. El compilador no traduce módulo a módulo para que el empaquetador los una después; recibe un archivo raíz, resuelve el grafo entero por su cuenta usando las rutas declaradas en el archivo de dependencias, y emite un único bloque de JavaScript. Esto significa que el empaquetador no puede dividir el código de Elm por rutas ni cargar partes bajo demanda del modo habitual, y que la caché de módulos del servidor de desarrollo opera con una granularidad más gruesa. A cambio, la compilación incremental del propio compilador es rápida, y el resultado se mantiene por debajo del umbral en que la espera se nota.

De esa granularidad se sigue una regla de configuración que ahorra bastantes horas de desconcierto: el complemento tiene que recibir la lista de directorios de fuentes que el archivo de dependencias declara, y el vigilante del servidor de desarrollo tiene que observar esos directorios enteros y no solo el archivo importado. Si se deja la vigilancia en manos del grafo del empaquetador, editar un módulo profundo que nadie importa desde JavaScript no dispara ninguna recompilación, y el navegador sigue mostrando código viejo sin decir nada. Es el fallo de integración más frecuente y el más difícil de diagnosticar, porque no produce ningún error: simplemente el cambio no aparece.

export default defineConfig({
  plugins: [ elm({ debug: true, optimize: false }) ],
  server: {
    watch: { ignored: ["!**/src/**/*.elm", "**/elm-stuff/**"] },
  },
});

import { Elm } from "./src/Main.elm";

const raiz = document.getElementById("panel");

const app = Elm.Main.init({
  node: raiz,
  flags: {
    apiUrl: import.meta.env.VITE_API_URL,
    usuario: null,
  },
});

Recarga en caliente cuando el estado es un solo valor

La sustitución de módulos en caliente es un problema difícil en la mayoría de los entornos porque el estado está repartido: vive dentro de instancias de componentes, en cierres, en variables de módulo, en referencias mutables que nadie enumeró nunca. Sustituir el código sin perder el estado exige adivinar qué estado pertenecía a qué pieza, y por eso la experiencia real oscila entre lo mágico y lo desconcertante. En Elm la pregunta cambia de naturaleza, porque todo el estado de la aplicación es un único valor inmutable que el entorno de ejecución tiene en la mano. Conservar el estado a través de una recarga consiste en serializar ese valor antes de sustituir el código y volver a inyectarlo después, y no hay nada que adivinar.

Hay un segundo aspecto de la recarga que decide la experiencia diaria y que casi nunca se configura con cuidado: qué ocurre cuando la compilación falla. La opción por defecto de muchos montajes es dejar la página como estaba y escribir el error en la terminal, lo cual funciona para quien tiene la terminal a la vista y desconcierta a quien no. La alternativa, que la mayoría de los complementos ofrecen, consiste en pintar el mensaje del compilador como una superposición sobre la aplicación. Vale la pena activarla por una razón que va más allá de la comodidad: los mensajes de este compilador son, junto con la exhaustividad, el activo pedagógico más grande del lenguaje, y esconderlos en una ventana que nadie mira desperdicia buena parte de lo que se vino a buscar.

flowchart TD
A[Guardar un archivo] --> B[El complemento invoca al compilador]
B --> C[Error de tipos]
B --> D[Compilacion correcta]
C --> E[Superposicion con el mensaje del compilador]
D --> F[Cambio solo en vista o logica]
D --> G[Cambio en la forma del modelo]
F --> H[Serializar modelo y reinyectar]
G --> I[Reinicio desde el estado inicial]
style D fill:#a6e3a1,color:#11111b
style C fill:#f38ba8,color:#11111b
style H fill:#89b4fa,color:#11111b

Tipar el borde con TypeScript

El punto delicado de la convivencia no es la construcción sino la frontera. El compilador de Elm garantiza todo lo que ocurre dentro de su grafo, y el de TypeScript todo lo que ocurre dentro del suyo, pero entre ambos hay tres pasos por los que viajan datos sin que ninguno de los dos los verifique: las banderas de arranque, los mensajes que salen por un puerto y los que entran. Del lado de Elm, las banderas y los puertos de entrada se decodifican, de modo que un dato mal formado produce un fallo explícito y localizado en lugar de propagarse. Del lado de TypeScript no hay nada equivalente por defecto: el módulo importado es un valor sin tipo y cualquier error de nombre o de forma pasa desapercibido hasta que la aplicación se ejecuta.

declare module "*.elm" {
  export namespace Elm {
    namespace Main {
      type Banderas = {
        apiUrl: string;
        usuario: string | null;
      };
      type App = {
        ports: {
          guardarEstado: { subscribe: (cb: (dato: string) => void) => void };
          recibirNotificacion: { send: (dato: unknown) => void };
        };
      };
      function init(opciones: { node: HTMLElement; flags: Banderas }): App;
    }
  }
}

Escribir a mano ese archivo de declaración funciona y es mejor que nada, pero tiene el defecto obvio de toda duplicación: cuando alguien cambia la firma de un puerto en Elm, la declaración se queda vieja y el error reaparece exactamente donde se creía haberlo eliminado. La alternativa madura consiste en generar las declaraciones a partir del código de Elm como paso de la construcción, de modo que la única fuente de verdad siga siendo el archivo fuente y la desincronización sea imposible. Existen herramientas de la comunidad dedicadas a ello, y algunas van más lejos y generan también los codificadores y decodificadores emparejados para que el formato de cada mensaje esté descrito una sola vez.

Queda por resolver una cuestión organizativa que suele decidirse por inercia y que conviene decidir a propósito: si el compilador de Elm debe vivir dentro del empaquetador o al lado. La integración por complemento gana en comodidad, porque hay un solo comando y un solo servidor, y pierde en calidad de diagnóstico, porque el mensaje del compilador atraviesa una capa que a veces lo recorta y a veces lo convierte en un error genérico del empaquetador. El proceso independiente invierte el balance: dos comandos que arrancar, pero el mensaje llega íntegro, la recompilación no compite con el resto del grafo y una avería en el complemento deja de ser un problema. En equipos donde varias personas están aprendiendo el lenguaje, el segundo modelo suele rendir más, precisamente porque el compilador es el profesor.

# Modelo integrado: un solo proceso
npm run dev

# Modelo separado: el compilador vigila por su cuenta
elm-watch hot &
vite --port 5173