Cuando ocurre un error JavaScript en producción, la stack trace apunta a tu bundle minificado (main.a8f42b.js:1:42819). Eso es inútil para depurar. Los source maps son los archivos JSON que tu bundler emite y le indican a Zenovay cómo traducir esos números de línea/columna de vuelta a tu código original.
El rastreo de errores — y los source maps con él — está disponible en planes Pro y superior.
Cómo funcionan los source maps en Zenovay
- Tu build produce un bundle (p. ej.
main.a8f42b.js) y un source map correspondiente (main.a8f42b.js.map). - Subes el source map a Zenovay a través de la API de rastreo de errores.
- Cuando llega un error, el tracker lo hace coincidir con tus maps subidos usando el archivo de bundle y el
releaseque subiste. - El dashboard muestra el archivo original, línea, columna y un fragmento de código.
Los source maps se almacenan contra un identificador de release — un SHA de Git, un tag semver o cualquier string que definas. Si el release del error no coincide con un map subido, verás la línea minificada en el dashboard.
Subir source maps
Los source maps se suben a través de la API de rastreo de errores. El endpoint acepta un cuerpo JSON:
POST https://api.zenovay.com/api/errors/{websiteId}/sourcemap
| Campo | Requerido | Descripción |
|---|---|---|
fileName | sí | El nombre bajo el que se debe almacenar el map (p. ej. main.js) |
fileUrl | sí | La URL pública del bundle al que pertenece el map |
release | recomendado | El identificador de release al que aplica este map (omitir = almacenar bajo default) |
mapContent | recomendado | El contenido del archivo .map |
mapUrl | opcional | Una URL de la que se puede recuperar el map, en lugar de incrustar mapContent |
Estos endpoints requieren una sesión Zenovay autenticada — pasa tu token de acceso al dashboard como token Bearer (el token de corta duración que tu navegador usa cuando has iniciado sesión en app.zenovay.com). No son alcanzables con una clave API REST zv_*.
curl -X POST "https://api.zenovay.com/api/errors/{websiteId}/sourcemap" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d @- <<'JSON'
{
"fileName": "main.js",
"fileUrl": "https://example.com/static/main.js",
"release": "v2.4.1",
"mapContent": "<contents of main.js.map>"
}
JSON
Para ver qué ya se ha subido para un sitio, lista tus maps:
GET https://api.zenovay.com/api/errors/{websiteId}/sourcemaps — añade ?release=v2.4.1 para filtrar a una versión específica.
Ejecuta la subida justo después de cada build de producción para que cada versión se entregue con maps, y comprueba el estado de la respuesta para que una subida fallida sea detectada en lugar de ignorarse silenciosamente. Ten en cuenta que el token de acceso es de corta duración, por lo que necesita estar fresco cada vez que subes — un token de sesión capturado del dashboard no seguirá siendo válido durante mucho tiempo.
Acerca del identificador de release
El campo release es el vínculo entre un error capturado y un map subido. Los errores se almacenan con el valor release bajo el que fueron reportados, y un map se asocia con un error cuando ambos comparten el mismo release.
Si quieres que los errores estén etiquetados con un release en el dashboard, tu aplicación necesita reportar ese release con cada error que envía. Sube maps bajo el mismo identificador, y los dos se alinean.
Verificar que funciona
- Sube un map y luego dispara un error conocido en producción.
- Abre el dashboard de tu sitio, ve a la pestaña Errors y abre el error.
- La sección de stack trace debe mostrar tu ruta de archivo original (p. ej.
src/components/Checkout.tsx:42) y una breve vista previa de código.
Si todavía muestra la línea minificada, comprueba:
- El release bajo el que se reportó el error coincide con el release bajo el que subiste el map.
- La
fileUrlque subiste coincide con el bundle del que provino el error. - El archivo
.mapno está truncado (una subida parcial puede dejarte sin un map utilizable).
Privacidad
Los source maps contienen todo tu código original. Se almacenan de forma privada, restringidos a tu sitio y nunca se sirven públicamente.