Por qué difieren: los bugs de dev que rompen en build

Si dev y build son dos estrategias distintas sobre el mismo grafo, la consecuencia es incómoda pero lógica: pueden diferir. Existe una clase entera de bugs que solo aparecen tras vite build —nunca en vite— y desconciertan porque el código “funcionaba”. No es que funcionara: es que el dev server es un intérprete permisivo que nunca ejerció las transformaciones donde el bug vive. El build es un compilador optimizador que sí las ejerce, y al hacerlo saca a la luz cualquier suposición frágil. Este nivel cataloga esas suposiciones para que dejen de emboscarte.

Orden y efectos secundarios

En dev, los módulos se evalúan en el orden en que el navegador los pide, siguiendo la topología natural del grafo. En build, Rollup o Rolldown hoistean y reordenan las declaraciones para concatenar módulos en un chunk: el orden de ejecución de los efectos al importar puede cambiar. Un módulo que en dev se inicializaba antes que otro quizá se inicialice después en el bundle, y todo código que dependa de un efecto secundario en tiempo de import se vuelve frágil.

El hoisting no es un capricho: es lo que permite que el bundler funda decenas de módulos en un solo ámbito, renombre lo que colisiona y elimine las barreras entre archivos. Pero al aplanar esa jerarquía, el orden temporal que en dev estaba garantizado por la secuencia de peticiones deja de estarlo, y pasa a depender del análisis del bundler, que optimiza por corrección estática, no por preservar tu orden implícito.

Los efectos que el orden del bundle puede alterar son casi siempre del mismo tipo:

• Registrar algo en un contenedor global en el momento de importar un módulo.
• Leer en el nivel superior una variable que otro módulo exporta.
• Inicializar un singleton cuyo orden de creación importa para el resto.
• Parchear un prototipo o instalar un polyfill como efecto de import.

Las dependencias circulares son el caso extremo. En dev, con módulos servidos por separado, un ciclo suele tolerarse porque el valor ya está disponible cuando se lee. En el bundle, tras el hoisting, el mismo ciclo puede exponer un binding aún sin inicializar y arrojar un undefined que en desarrollo jamás viste.

// a.ts importa de b.ts y b.ts importa de a.ts: un ciclo
// En dev el orden de peticiones lo salva; tras el hoisting del build,
// valor puede leerse antes de asignarse y quedar en undefined.
import { valor } from "./b";
export const derivado = valor * 2;   // NaN si valor aun no existe

Tree shaking que borra lo que sí usabas

En dev, tu código nunca se poda: se sirve entero. En build, el tree shaking analiza el grafo ESM y elimina todo export que cree muerto. El problema surge cuando algo parece muerto al análisis estático pero está vivo en tiempo de ejecución: acceso dinámico a propiedades, reflexión, un decorador con efecto, o un módulo mal declarado con sideEffects: false cuando en realidad sí los tiene. El bundler lo borra con toda la razón formal, y tu producción se rompe.

El análisis estático se equivoca cuando el uso no es visible en el texto del módulo:

• Acceso a propiedades por clave calculada en tiempo de ejecución.
• Reflexión o metaprogramación sobre un import de namespace.
• Efectos declarados como inexistentes con un sideEffects: false incorrecto.
• Registros implícitos que dependen de que el import ocurra, no de que se use su valor.

// El analisis estatico no ve este uso: cree que los temas estan muertos
import * as temas from "./temas";
const nombre = leerDeConfig();       // valor dinamico, ilegible en build
export const activo = temas[nombre]; // en produccion puede ser undefined

La declaración de sideEffects es un contrato peligroso precisamente porque el análisis confía en ella ciegamente. Si marcas un paquete como libre de efectos para que el bundler pode agresivamente, pero uno de sus módulos registra un componente o parchea un prototipo al importarse, el bundler lo eliminará por creerlo inerte y el efecto nunca ocurrirá. En dev no lo notas porque nada se poda; en build, el registro simplemente desaparece.

{
  "name": "mi-libreria",
  "sideEffects": ["./src/registrar-globales.js", "*.css"]
}

La otra mitad del fenómeno es la eliminación de código muerto por sustitución. Vite reemplaza import.meta.env.DEV por el literal true o false mediante define, que es una sustitución textual, no semántica. Tras fijar el literal, el minificador poda la rama inalcanzable. Si tu lógica esperaba que esa rama existiera en runtime, desaparece. La lección: lo que en dev es una variable, en build puede ser una constante ya resuelta y una rama ya borrada.

Globals, process y variables de entorno

El navegador no tiene process, ni Buffer, ni __dirname. En dev, con Vite sirviendo módulos y ciertos polyfills o fugas del entorno de Node, un código que lee process.env.ALGO a veces parece funcionar. En el build de cliente ese process no existe, y salvo que lo hayas sustituido con define, obtienes un ReferenceError en producción. La forma correcta en Vite es import.meta.env, y solo las variables con prefijo VITE_ se inyectan al cliente.

// Correcto en el cliente: solo variables con prefijo VITE_ llegan al bundle
const api = import.meta.env.VITE_API_URL;   // inyectada en build
const modo = import.meta.env.MODE;          // "development" o "production"

// Peligroso: process no existe en el navegador
const roto = process.env.SECRETO;           // ReferenceError en produccion

Que solo se inyecten las variables con prefijo VITE_ no es un capricho, sino una defensa de seguridad. Tu entorno de servidor contiene secretos —claves de API privadas, cadenas de conexión— y si Vite inyectara todo process.env en el bundle de cliente, esos secretos viajarían al navegador de cualquier usuario. El prefijo obligatorio convierte la exposición en un acto deliberado: solo lo que marcas explícitamente como público cruza al cliente.

El desajuste de globales tiene varias caras, y conviene reconocerlas todas:

• process y Buffer: existen en Node y no en el navegador.
• __dirname y __filename: propios de CommonJS, ausentes en el ESM de navegador.
• global frente a globalThis: solo el segundo es portable entre entornos.
• Variables sin prefijo VITE_: quedan fuera del bundle de cliente a propósito.

Hay un matiz que atrapa a mucha gente: import.meta.env.MODE y el valor de NODE_ENV los fija el modo, no el comando. vite build usa por defecto el modo production, pero puedes correr vite build --mode staging y obtener otro conjunto de variables. Confundir “estoy en build” con “estoy en producción” es un error sutil: son ejes independientes, y el próximo nivel sobre cliente y SSR lo hace aún más evidente.

flowchart TD
S[Un mismo modulo fuente] --> DEV[Dev sirve ESM sin tocar el grafo]
S --> BUILD[Build reordena poda y sustituye]
DEV --> OK[Funciona porque nada se poda ni se mueve]
BUILD --> R1[Cambia el orden de los efectos al importar]
BUILD --> R2[Tree shaking borra lo usado por reflexion]
BUILD --> R3[process y globals no existen en el bundle]
style S fill:#89b4fa,color:#11111b
style OK fill:#a6e3a1,color:#11111b
style R1 fill:#f38ba8,color:#11111b
style R2 fill:#f38ba8,color:#11111b
style R3 fill:#f38ba8,color:#11111b