Configura mapas de origen de forma segura para leer errores frontend en producción

Por qué los errores frontend en producción son difíciles de leer

Los errores frontend en producción suelen llegar como un mensaje corto más una traza que parece específica, pero no te dice realmente qué falló.

Un informe típico puede verse así:

TypeError: Cannot read properties of undefined (reading 'name')
    at t (app.3f9c1a2b.js:1:28417)
    at e (app.3f9c1a2b.js:1:29102)
    at HTMLButtonElement.<anonymous> (app.3f9c1a2b.js:1:30511)

Esos nombres de archivo y números de línea son reales, pero apuntan al bundle final que descargan tus usuarios, no a los archivos que editas. En builds de producción, el código se minifica (los nombres se acortan, se quita el espaciado), se reordena y a menudo se divide en chunks. Eso ayuda a la velocidad de carga, pero hace que los fallos sean difíciles de interpretar.

La minificación también elimina pistas útiles. Los nombres de funciones pasan a ser letras, muchas sentencias se agrupan en una sola línea y varios archivos originales pueden terminar fusionados en un mismo archivo de salida. Así que cuando la traza dice app.3f9c1a2b.js:1:28417, esa ubicación puede corresponder a un componente React, una utilidad compartida o una librería empaquetada junto a tu código.

Lo que quieres es simple: información legible y exacta de archivo y línea, sin facilitar que el público descargue tu código. Por eso los equipos configuran mapas de origen de forma segura, para que las herramientas de monitorización traduzcan trazas minificadas de vuelta a tu código original.

Esto importa sobre todo cuando no tienes tiempo para adivinar:

• un incidente en producción donde cada minuto te cuesta usuarios
• un hotfix apresurado donde necesitas el cambio más pequeño y seguro
• un bug que ocurre solo en un navegador o dispositivo
• un problema que aparece solo después de un deploy (desajuste de release)
• un informe de cliente con detalles limitados

Si heredaste un frontend generado por IA, puede ser peor. Los bundles a menudo ocultan lógica enredada, y un puntero limpio al archivo y línea exactos marca la diferencia entre un parche rápido y horas de ensayo y error.

Mapas de origen en lenguaje llano (qué hacen y qué contienen)

Un mapa de origen es un pequeño archivo “decodificador” que le dice al navegador (y a un registrador de errores) cómo un bundle de producción minificado se mapea de vuelta al código original.

Por eso un error puede apuntar a app.8f3a1c2.js:1:53241 en lugar de src/components/CheckoutButton.tsx:47. Los mapas de origen salvan esa distancia traduciendo la línea:columna del bundle al archivo, línea y columna originales.

Qué contiene un mapa de origen (y por qué te importa)

Los source maps pueden incluir más que números de línea:

• rutas de archivo a tus módulos originales (como src/pages/login.tsx)
• nombres de símbolos (nombres de funciones y variables)
• el código fuente original en sí vía sourcesContent (el mayor riesgo de seguridad)

Incrustar sourcesContent es cómodo porque la depuración funciona incluso si el repo no está disponible para la herramienta que hace el mapeo. Pero si el mapa se filtra, tu código real puede filtrarse con él.

Trata los mapas de origen como artefactos internos, no como activos públicos.

Qué pueden y qué no pueden hacer los source maps

Los mapas de origen te ayudan a localizar el problema rápidamente. No solucionan el problema.

Si un usuario pulsa “Pagar” y ves “Cannot read properties of undefined”, un source map no evitará el bug. Te dirá qué archivo y línea intentaron leer ese valor faltante, para que puedas añadir la comprobación adecuada, manejar un estado vacío o arreglar el flujo de datos.

Haz un plan seguro antes de generar nada

Los source maps funcionan mejor cuando decides desde el principio quién debe poder acceder a ellos. Muchos equipos generan mapas “por si acaso” y luego publican código legible a cada visitante por accidente.

Mantén producción rápida y la depuración legible

Puedes mantener los bundles de producción totalmente minificados para los usuarios y aun así obtener trazas legibles para tu equipo. Los source maps son para depuración, no para rendimiento.

Si ya estás persiguiendo crashes en producción, céntrate primero en la ruta de depuración: cómo vas a recopilar trazas y cómo las vas a resolver de vuelta al código original.

Decide dónde viven los mapas y quién puede acceder a ellos

Antes de generar nada, elige un modelo de hosting que se ajuste a tu nivel de riesgo:

• Servidor web público: fácil de configurar, lo más fácil de exponer por accidente.
• Almacenamiento privado: los mapas no son accesibles por usuarios normales; solo tu tooling puede recuperarlos.
• Control de acceso: limitado a tu equipo, CI y monitorización de errores.
• Retención: conserva los mapas solo el tiempo que los necesites.

Luego decide qué incluir. Si incrustas sourcesContent, el mapa puede contener tu código completo. Muchos equipos eliminan sourcesContent y confían en repos privados o en almacenamiento privado al resolver errores.

Paso a paso: genera y verifica los source maps

Piensa en los mapas de origen como artefactos de build que puedes crear en cualquier momento, pero compartir solo cuando lo decidas.

1) Activa la generación de source maps en tu herramienta de build

La mayoría de herramientas de build tienen una sola opción para esto. Busca sourcemap, sourceMap o devtool. Para depuración en producción, prefiere mapas completos (no “cheap”) para que los números de línea y columna coincidan con los que ves en los logs reales.

Si tu app produce múltiples bundles (app principal, vendor, chunks), asegúrate de que se generen mapas para todas las salidas.

2) Compila localmente y confirma que existen los archivos .map

Ejecuta el mismo comando que usas para un build de producción real. Inspecciona la carpeta de salida y confirma que ves archivos que terminan en .map.

Cada archivo de JavaScript minificado suele referenciar su mapa, normalmente con un comentario cerca del final:

//# sourceMappingURL=app.abc123.js.map

Si ese comentario falta, muchas herramientas de monitorización no podrán emparejar trazas con las fuentes.

3) Comprueba que el mapa coincide con el bundle

Elige un bundle y su mapa y confirma:

• el archivo .map es JSON válido
• el mapa tiene un campo file que parece el nombre del bundle
• el mapa tiene sources no vacíos

Una comprobación práctica: abre el archivo minificado en las devtools del navegador. Si el mapa está presente, el panel Sources debería mostrar los nombres de archivo originales y permitirte saltar a ubicaciones reales.

4) Registra la versión exacta que publicas

Antes de desplegar, registra el hash del commit, el ID del build o la etiqueta de release para esta salida y guárdalo con los artefactos. Más tarde, esa etiqueta es cómo encuentras el mapa correcto para una traza de producción.

Evita sobrescribir mapas antiguos sin una etiqueta de versión.

Paso a paso: publica source maps de forma privada para trazado de errores

Publicar source maps no significa ponerlos en tu sitio público. El enfoque más seguro es generarlos durante el build y subirlos solo a tu herramienta de monitorización de errores para que pueda desminificar trazas.

1) Elige un esquema de nombres de release que no cambies

Tu herramienta de monitorización necesita un valor de release consistente para emparejar errores con los mapas correctos. Mantenlo aburrido: un SHA de git, o algo como [email protected]+build.417.

Usa el mismo valor en tres sitios: tu pipeline de build, el frontend desplegado y el paso de subida a la monitorización.

2) Sube los source maps a la herramienta de monitorización, no al servidor web

Un flujo común:

• build con source maps activados (mantén los archivos .map como artefactos)
• despliega solo los bundles .js minificados a producción (sin los .map)
• sube los .map al proveedor de monitorización bajo el mismo release/versión
• configura la herramienta con la ruta URL de los bundles que debe emparejar
• provoca un error de prueba en staging para confirmar que se resuelve a nombres de archivo y números de línea reales

Algunas herramientas tardan un minuto en procesar mapas, así que prueba tras una breve espera.

3) Asegúrate de que la herramienta pueda emparejar rutas exactamente

La mayoría de fallos de “mapa de origen faltante” son desajustes de rutas. La herramienta intenta emparejar lo que el navegador reportó con lo que subiste.

Si el mapeo no funciona, comprueba:

• los nombres de bundle coinciden exactamente (incluyendo hashes)
• el prefijo de URL configurado coincide con tu CDN o base de assets
• subiste mapas del build exacto que está desplegado
• no estás reutilizando identificadores de release antiguos

Cómo evitar filtrar código cuando usas source maps

Los source maps son excelentes para depurar en producción, pero pueden exponer tu app si los publicas descuidadamente. Un valor por defecto seguro: no hagas que los archivos .map sean descargables públicamente a menos que realmente te importe que cualquiera lea tu código cliente.

Mantén los .map fuera de Internet público

Dos enfoques cubren la mayoría de equipos:

• No despliegues los .map; súbelos solo a tu tracker de errores.
• Bloquea las peticiones a *.map en tu CDN o servidor web.

Chequeo rápido: abre tu sitio en una ventana de incógnito, adivina una URL probable de mapa (como app.js.map) y confirma que devuelve 404 o forbidden.

Si debes alojar mapas, protégelos

Si necesitas autoalojar mapas para tooling personalizado, exige autenticación y limita quién puede acceder. Un endpoint solo por VPN, listas de IP permitidas o URLs firmadas con expiración corta son razonables.

Recuerda también: incluso si tus bundles no enlazan mapas vía sourceMappingURL, un archivo .map público sigue siendo una fuga si es accesible.

Reduce lo que contiene el mapa (cuando el riesgo es alto)

Si tu tooling lo permite, considera eliminar sourcesContent para que el mapa contenga solo los mapeos y no el texto completo del código. Así obtienes punteros a nivel de línea sin entregar el código.

Cómo trazar una traza minificada hasta la línea exacta

Una traza minificada parece inútil porque apunta a nombres cortos y funciones diminutas, además de una línea y columna que no coinciden con tu fuente.

Empieza por encontrar el primer frame de la pila que pertenezca a tu app (no al navegador, extensiones o scripts de terceros). Buscas un nombre de bundle y una posición, por ejemplo:

at t (app.3f2c1.js:1:28491)

Ese :1:28491 es la clave. Con source maps disponibles para tu herramienta (o para un paso de mapeo local), traduce esa ubicación del bundle a un archivo, línea y columna reales.

Una vez que aterrices en la línea mapeada, no te pares en la sentencia que lanza. Sube a ver qué valores se pasaron. Muchos errores de “undefined” se originan antes.

Una forma simple de trabajar la traza:

• mapea el frame más alto perteneciente a tu app desde línea:columna del bundle a línea:columna del source
• abre el archivo mapeado y encuentra la sentencia exacta
• revisa el frame llamador para ver qué argumentos se pasaron
• añade una pequeña pista (log, métrica o guard) para confirmar el valor fallido
• decide: parche rápido ahora, o refactor si el patrón se repite

Ejemplo: la traza dice app.3f2c1.js:1:28491. Tras mapear, aterrizas en src/components/CheckoutButton.tsx:42:17 en user.profile.name.trim(). El verdadero bug no es que trim falló: es que user.profile a veces falta.

Ejemplo: convertir “Cannot read properties of undefined” en un arreglo

Una historia común: todo parece bien en staging, y tras un deploy a producción ves un pico de “Cannot read properties of undefined (reading 'name')”. Ocurre solo para algunos usuarios, así que es difícil reproducir.

Sin mapas de origen, el reporte suele verse así:

TypeError: Cannot read properties of undefined (reading 'name')
    at tI (app.3f2c1a9.js:1:184233)
    at nA (app.3f2c1a9.js:1:186901)

Con los source maps correctos subidos de forma privada a tu herramienta de monitorización, el mismo crash se vuelve legible:

TypeError: Cannot read properties of undefined (reading 'name')
    at renderUserBadge (src/components/UserBadge.tsx:42:17)
    at ProfileHeader (src/pages/Profile.tsx:118:9)

Ahora puedes abrir UserBadge.tsx y ver la suposición equivocada:

// UserBadge.tsx (before)
export function UserBadge({ user }: { user: any }) {
  return <span>{user.profile.name}</span>;
}

Para algunos usuarios, profile falta (cuenta nueva, respuesta API parcial, datos en caché), así que user.profile es undefined y leer .name provoca el crash.

El arreglo más pequeño y seguro es manejar la forma faltante y mostrar un valor por defecto:

// UserBadge.tsx (after)
export function UserBadge({ user }: { user: any }) {
  const name = user?.profile?.name;
  return <span>{name ?? "Anonymous"}</span>;
}

Para reducir repeticiones, añade una barrera:

• valida la respuesta API y rellena valores por defecto antes de renderizar
• endurece los tipos para que los campos opcionales deban manejarse
• añade un caso de prueba para “usuario nuevo sin profile”

Errores comunes que rompen los source maps (o los exponen)

Los mapas de origen solo son útiles cuando coinciden con el JavaScript que los usuarios ejecutaron. También son fáciles de filtrar si los despliegas como cualquier otro archivo estático.

1) El mapa no coincide con el build desplegado (mismatch de hash)

Si subes mapas de un build distinto al que está en producción, las herramientas mostrarán números de línea equivocados, nombres de archivo sin sentido o no podrán mapear nada. Esto suele pasar cuando el CI buildea dos veces: una para desplegar y otra para subir mapas.

Chequeo rápido: abre el .js desplegado y busca el comentario sourceMappingURL. Si apunta a un mapa que no subiste (o los hashes no coinciden), el mapeo no funcionará.

2) publicPath o URL de assets incorrecta (las búsquedas fallan silenciosamente)

Incluso mapas correctos no resolverán si las URLs no coinciden con la realidad. Causas comunes: usar un CDN en producción pero dejar una ruta local en la configuración, o servir la app desde /app/ mientras los assets asumen /.

Síntomas: peticiones a .map devuelven 404/403, o la herramienta de monitorización reporta artefactos faltantes. Arregla asegurándote de que la app reporta la URL base real de assets para producción y que la ruta que usa tu herramienta coincide con las URLs desplegadas.

3) Publicar mapas accidentalmente a usuarios

Si tu paso de despliegue sube toda la carpeta dist/, puedes publicar tus maps a cualquiera que sepa dónde buscar.

Buenas prácticas: no desplegar .map o restringir el acceso en el borde.

4) Falta de tagging de release/version (los errores se mapean al código equivocado)

Sin un identificador de release claro, tu sistema de monitorización puede adjuntar los errores de hoy a mapas de ayer, especialmente si los nombres de archivo se reutilizan (como app.js).

Haz que el etiquetado de release sea obligatorio en CI: un release por despliegue y sube los artefactos coincidentes bajo ese mismo release.

Lista rápida y siguientes pasos

Antes de publicar, haz una pasada corta que cubra exactitud del build, seguridad y una prueba real de depuración:

• registra un ID de release único y úsalo de forma consistente (build, deploy, subida a monitorización)
• confirma que los mapas se generan para el build de producción
• sube los mapas de forma privada a tu proveedor de monitorización
• confirma que los archivos .map no son accesibles públicamente
• provoca un error controlado y verifica que se resuelve a un archivo y línea reales

Si tratas con una app generada por IA que publica builds rotos, releases inconsistentes o errores en producción ilegibles, FixMyMess (fixmymess.ai) puede ayudar diagnosticando la base de código, corrigiendo lógica y problemas de seguridad, y dejando el manejo de monitorización y source maps funcionando sin exponer tu fuente. Ofrecen una auditoría de código gratuita antes de cualquier compromiso.