Source maps: del código minificado al original

Tras minificar, tu código es un amasijo de una sola línea con variables llamadas a, b y o: imposible de depurar tal cual. El source map es la pieza que reconcilia las dos exigencias en conflicto —enviar algo diminuto y, a la vez, poder leerlo cuando algo falla—. Es un archivo aparte, con extensión .map, que guarda una correspondencia exacta entre cada posición del código generado y la posición del código fuente de la que salió. No cambia lo que se ejecuta ni un byte; es una capa de indirección pura que las herramientas de desarrollo siguen hacia atrás para mostrarte tu TypeScript original en lugar del engrudo minificado.

Qué hay dentro de un .map

Un source map es un JSON con una forma estándar, la versión 3, que llevan décadas hablando navegadores y herramientas. Sus campos son pocos y cada uno tiene un papel nítido:

{
  "version": 3,
  "file": "app.min.js",
  "sources": ["src/saludar.ts"],
  "sourcesContent": ["export function saludar(n) { ... }"],
  "names": ["saludar", "nombreDeUsuario"],
  "mappings": "AAAA,SAASA,QAAT,CAAkBC..."
}

sources lista los archivos originales; sourcesContent, opcionalmente, incrusta su texto completo para que el depurador no tenga que ir a buscarlos; names guarda los identificadores originales que el mangling destruyó, para poder mostrarte nombreDeUsuario donde el código dice o. Pero el corazón es mappings: una cadena que codifica, para cada posición del archivo generado, de qué línea y columna del original procede.

Los campos, uno a uno:

• version: siempre 3, el formato vigente que entienden navegadores y herramientas.
• sources: la lista de archivos originales de los que salió el código generado.
• sourcesContent: opcional, el texto íntegro de esas fuentes incrustado en el mapa.
• names: los identificadores originales que el mangling reemplazó por letras.
• mappings: el núcleo, las posiciones codificadas en VLQ base 64 y en delta.

Esa cadena no es legible por casualidad. Cada segmento codifica hasta cinco números —columna generada, índice de fuente, línea original, columna original e índice de nombre— con VLQ en base 64, y todos van en delta, relativos al segmento anterior. La codificación en diferencias es lo que mantiene el mapa compacto pese a describir cada token: un archivo de miles de líneas cabe en un JSON manejable porque casi nunca guarda una posición absoluta, sino el pequeño salto desde la anterior.

Los cinco números de cada segmento, en orden:

• Columna generada: dónde empieza el tramo en la línea del archivo minificado.
• Índice de fuente: a cuál de los sources pertenece el original.
• Línea y columna originales: el punto exacto del que salió ese tramo.
• Índice de nombre: opcional, qué identificador de names le corresponde.

Cómo el navegador sigue el rastro

Para que la traducción ocurra, el archivo generado debe declarar dónde está su mapa. Lo hace con un comentario especial en su última línea, o con una cabecera HTTP equivalente:

// ...codigo minificado en una sola linea...
//# sourceMappingURL=app.min.js.map

Cuando abres las DevTools, el navegador ve ese comentario, descarga el .map, decodifica los mappings VLQ y construye una tabla de posiciones bidireccional. A partir de ahí, cada vez que pones un breakpoint o lees una traza de pila, traduce la posición del código generado a tu fuente original y te muestra el archivo tal como lo escribiste, con sus nombres y sus líneas. Si el mapa trae sourcesContent, ni siquiera necesita los archivos originales: los lleva dentro.

Hay un detalle que explica cómo el mapa sobrevive a toda la tubería. Tu código no se minifica de golpe: primero se transpila —de TypeScript a JavaScript—, luego se empaqueta, luego se minifica. Cada etapa produce su propio source map, y las herramientas los componen: el mapa final no apunta al paso anterior, sino todo el camino de vuelta hasta tu .ts original. Es un mapa de un mapa de un mapa, colapsado en uno solo que salta directamente del engrudo minificado a la línea que escribiste.

Cada etapa de la tubería aporta su tramo al mapa final:

• Transpilar: de tu .ts con tipos y JSX al JavaScript equivalente; primer mapa.
• Empaquetar: de muchos módulos a unos pocos chunks; el bundler reubica cada línea y actualiza el mapa.
• Minificar: del chunk legible al chunk apretado; el minificador compone su mapa sobre el anterior.
• Componer: las herramientas funden los tres tramos en un solo .map que apunta al origen real.

flowchart LR
TS[Tu codigo TypeScript] --> B[Transpilar empaquetar minificar]
B --> JS[app.min.js que se ejecuta]
B --> MAP[app.min.js.map]
MAP -.->|traduce posiciones| TS
JS -.->|apunta a| MAP
style TS fill:#89b4fa,color:#11111b
style JS fill:#f9e2af,color:#11111b
style MAP fill:#a6e3a1,color:#11111b

Tres tipos: inline, external, hidden

Aquí está la decisión práctica. El mismo mapa puede entregarse de tres formas, y la diferencia entre ellas no es su contenido, sino quién puede seguir el puntero.

El inline es cómodo en desarrollo porque no hay archivo suelto ni petición extra, pero duplica con creces el tamaño del JavaScript, así que en producción es inaceptable. El external es la forma habitual cuando quieres que los mapas estén disponibles: el .js viaja ligero y el .map solo se pide bajo demanda. El hidden es el más sutil y prepara el terreno del siguiente nivel: produce el .map pero corta el hilo que lo anuncia, de modo que puedas quedártelo para depurar en privado sin ofrecérselo al mundo.

La elección del tipo se reduce a dónde estás y a quién quieres dejar traducir:

• inline en desarrollo: comodidad máxima, sin archivos sueltos; el tamaño no importa en local.
• external cuando sirves los mapas: el .js viaja ligero y el .map solo se pide al depurar.
• hidden en producción con servicio de errores: conservas el mapa para ti, no para el público.
• false si no vas a depurar el build: ni generas ni sirves nada, y ahorras tiempo de build y disco.

// vite.config.ts — cada tipo se pide con un valor distinto
export default defineConfig({
  build: {
    sourcemap: "hidden",   // true = external, "inline" o false tambien valen
  },
});

Generar mapas no es gratis, y conviene saber qué cuesta cada cosa:

• Tiempo de build: producir el mapa añade trabajo; en inline, además, infla el .js.
• Disco y despliegue: los .map externos son archivos más que gestionar y, quizá, subir a un servicio.
• Riesgo de exposición: un mapa servido en abierto entrega tu fuente; por eso hidden existe.
• Coste en runtime: ninguno, y esto es lo decisivo: el mapa jamás entra en el camino de ejecución.