Errores y source maps: trazas legibles en producción

Un usuario dispara una excepción en tu Worker y la traza que llega a tus logs dice TypeError en index.js:1:48210. Esa línea es inútil: apunta al bundle minificado de una sola línea, con nombres de una letra, que Wrangler generó para producción —no a tu código—. Existe una brecha semántica entre lo que escribiste y lo que corre, y una traza cruda vive del lado equivocado de esa brecha. Los source maps son el puente: le enseñan a Cloudflare a traducir esa posición de vuelta a carrito.ts:42, dentro de aplicarDescuento, y de golpe el error deja de ser ruido y se vuelve accionable. Y en el edge esto se resuelve sin el dilema clásico del navegador —exponer tu fuente para poder leerla—, porque el mapa vive en privado, del lado de Cloudflare.

Por qué la traza de producción es ilegible

Antes de subir tu Worker, Wrangler lo empaqueta y lo minifica con esbuild: reúne todos tus módulos en un único archivo, elimina espacios y comentarios, y renombra las variables a identificadores de una o dos letras para que el bundle pese lo mínimo. El resultado es un index.js de una sola línea gigantesca, funcionalmente idéntico a tu código pero visualmente irreconocible.

Cuando ese código lanza una excepción, la traza de pila describe posiciones de ese archivo generado, no del tuyo. Te roba justo lo que necesitas para actuar:

• El nombre real de la función donde falló, sustituido por una letra como a o t.
• El archivo de origen, colapsado en un único bundle que reúne decenas de módulos.
• La línea y la columna con sentido, reducidas a la línea 1 y una columna de decenas de miles.

Sin traducción, depurar una excepción de producción es adivinar a ciegas.

Qué es un source map

Un source map es un archivo .map que acompaña al bundle y contiene la correspondencia exacta entre cada posición del código generado y su posición original: qué archivo, qué línea, qué columna y qué nombre tenía cada símbolo antes de la minificación. Con él, index.js:1:48210 se traduce sin ambigüedad a carrito.ts:42:8, aplicarDescuento. Es, literalmente, el diccionario que deshace la transformación del empaquetado.

Activar upload_source_maps

En Workers todo se reduce a una clave en el manifiesto:

{
  "name": "mi-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-01-01",
  "upload_source_maps": true,
  "observability": { "enabled": true }
}

Con upload_source_maps en true, cada wrangler deploy genera los source maps del bundle y los sube a Cloudflare junto al código. No se sirven a los usuarios ni se exponen en ninguna URL pública: quedan almacenados del lado de la plataforma, con el único propósito de traducir trazas. A partir de ahí, cuando tu Worker lanza una excepción, Cloudflare usa el mapa correspondiente para remapear la traza y te la muestra ya legible en el panel de observabilidad, en Workers Logs y en wrangler tail.

# Genera y sube los source maps como parte del despliegue
wrangler deploy
# En observabilidad veras la traza remapeada:
#   TypeError en src/carrito.ts:42:8  ->  aplicarDescuento

flowchart LR
Src[tu codigo carrito.ts] --> Build[wrangler deploy con esbuild]
Build --> Min[bundle minificado index.js]
Build --> Map[source map generado]
Map -->|subido en privado| CF[almacen de Cloudflare]
Min --> Prod[Worker en produccion]
Prod -->|excepcion| Trace[traza cruda index.js 1 48210]
Trace --> Remap[Cloudflare remapea con el mapa privado]
CF --> Remap
Remap --> Legible[traza legible carrito.ts 42 aplicarDescuento]
style Map fill:#f9e2af,color:#11111b
style CF fill:#cba6f7,color:#11111b
style Legible fill:#a6e3a1,color:#11111b
style Trace fill:#f38ba8,color:#11111b

Qué se remapea, y sus límites

El remapeo lo hace la plataforma en el momento de mostrarte la traza, no tu código en ejecución. Esto tiene dos consecuencias prácticas. La primera: para aprovecharlo, deja que las excepciones lleguen a la plataforma —bien porque se propagan sin capturar, bien porque las registras enteras— y lee la traza ya traducida en observabilidad, en lugar de intentar simbolizar a mano una cadena error.stack que en tiempo de ejecución sigue apuntando al bundle. La segunda: hay límites de tamaño para los source maps que subes (del orden de unos pocos megabytes comprimidos), así que Workers enormes pueden requerir dividir el código o revisar la configuración del bundle.