Saltar al contenido

Documentación

Source maps y CLI

Sube tus source maps desde CI para que los errores muestren tu archivo y línea originales, no el JavaScript minificado.

En producción tu JavaScript está minificado: un error dice index-3fa2.js:1:48211. Si subes los source maps de cada versión, Wutbug traduce los stack traces a tu código original (archivo, línea y el fragmento de código) en el dashboard y en las respuestas del servidor MCP.

Cómo funciona

  1. Tu build genera archivos .map junto a los .js.
  2. En CI, el CLI sube los .map con un identificador de versión (--release).
  3. Tu app inicializa el SDK con el mismo release.
  4. Cuando llega un reporte, Wutbug busca los mapas de ese release por la URL de cada archivo del stack trace.

1. Pasa el release al SDK

TypeScript
wutbug.init({
  projectKey: 'pk_tu_key',
  endpoint: 'https://api.wutbug.dev',
  release: import.meta.env.VITE_RELEASE, // por ejemplo el SHA del commit
});

Con la etiqueta script: data-release="…".

2. Genera los source maps

HerramientaConfiguración
Vitebuild: { sourcemap: 'hidden' } en vite.config.ts
Next.jsproductionBrowserSourceMaps: true en next.config.ts
webpackdevtool: 'hidden-source-map'
esbuild--sourcemap=external

Las variantes hidden generan los .map sin el comentario //# sourceMappingURL, así tu código fuente no queda expuesto públicamente.

3. Sube los mapas desde CI

Crea la secret key (sk_…) del proyecto en el dashboard, en Proyectos → Source maps, y guárdala como secreto de CI en WUTBUG_SECRET_KEY.

Terminal
npx @wutbug/cli sourcemaps upload ./dist/assets \
  --release "$GITHUB_SHA" \
  --url-prefix /assets/ \
  --api https://api.wutbug.dev \
  --delete
OpciónDescripción
<dir>Carpeta donde buscar archivos *.js.map (recursivo).
--release <versión>Obligatoria. El mismo valor que pasas a init({ release }).
--url-prefix <ruta>Ruta URL donde se sirve <dir>. Por defecto /. Ejemplo: si dist/assets/index-3fa2.js se sirve en https://app.acme.com/assets/index-3fa2.js, usa /assets/.
--api <url>URL de la API. Por defecto $WUTBUG_API_URL.
--deleteBorra los .map locales después de subirlos, para que no se publiquen.
Variable de entornoDescripción
WUTBUG_SECRET_KEYObligatoria. Secret key del proyecto (sk_…).
WUTBUG_API_URLURL de la API, si no usas --api.

Ejemplo con GitHub Actions y Vite

.github/workflows/deploy.yml
- name: Build
  run: npm run build
  env:
    VITE_RELEASE: ${{ github.sha }}

- name: Subir source maps a Wutbug
  run: npx @wutbug/cli sourcemaps upload ./dist/assets --release ${{ github.sha }} --url-prefix /assets/ --delete
  env:
    WUTBUG_SECRET_KEY: ${{ secrets.WUTBUG_SECRET_KEY }}
    WUTBUG_API_URL: https://api.wutbug.dev

Next.js

Los archivos de cliente de Next.js se sirven bajo /_next/static/:

Terminal
npx @wutbug/cli sourcemaps upload .next/static --release "$GIT_SHA" --url-prefix /_next/static/ --delete

Problemas comunes

  • El stack trace sigue minificado. Revisa que el release del reporte (visible en el dashboard) sea idéntico al que usaste al subir, y que --url-prefix coincida con la ruta real de los archivos.
  • "Set WUTBUG_SECRET_KEY…": falta la variable o no empieza con sk_.
  • La secret key se filtró. Genera una nueva en el dashboard: la anterior deja de funcionar. Solo guardamos un hash de la key, así que no podemos mostrártela de nuevo.
← AnteriorCaptura automáticaSiguiente →MCP / Conectar IA