Source maps en CI
Sube los source maps y registra la versión desde tu compilación, con un ejemplo completo de GitHub Actions, para que las pilas muestren tus propios archivos y los problemas digan qué cambio los empezó.
Esta guía es para quien es dueño de la compilación. Funciona igual para Sypnia Cloud y para un motor con alojamiento propio; solo cambia una variable. Para una app Next.js no la necesitas: @sypnia/next sube los source maps durante next build, mira Next.js.
Al final tendrás: cada despliegue registrado como una versión (release) con su commit, sus source maps guardados en privado en Sypnia, y ningún archivo .map publicado con tu sitio.
Necesitas: un proyecto, una compilación que pueda escribir source maps, y un token de API con el permiso admin.
Las tres reglas
- Un solo nombre para la versión. El texto que pasas a
initcomoreleasey el texto con el que subes deben ser idénticos. Usa el commit corto de git para ambos. - Sube después de empaquetar y antes de desplegar. Los source maps deben estar en Sypnia antes de que el primer visitante cargue el código nuevo.
- Nunca publiques los source maps. Contienen tu código fuente. El comando de subida los borra de la salida de la compilación.
Configúralo
Haz que la compilación escriba source maps, y que conozca su versión
Vite
vite.config.ts import { defineConfig } from 'vite'; export default defineConfig({ build: { sourcemap: 'hidden' }, define: { __RELEASE__: JSON.stringify(process.env.RELEASE ?? '') }, });src/main.ts import { init } from '@sypnia/browser'; declare const __RELEASE__: string; init({ project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e', release: __RELEASE__ || undefined, });webpack
webpack.config.js const webpack = require('webpack'); module.exports = { devtool: 'hidden-source-map', plugins: [new webpack.DefinePlugin({ __RELEASE__: JSON.stringify(process.env.RELEASE ?? '') })], };esbuild
Terminal esbuild src/main.ts --bundle --minify --sourcemap=external --outdir=dist \ --define:__RELEASE__="\"$RELEASE\""hidden(oexternal) escribe los archivos.mapsin dejar en el JavaScript un comentario que apunte a ellos.Deberías verDespués deRELEASE=4f2a91c npm run build,disttiene archivos.jsy un.mapjunto a cada uno.Crea el token y guárdalo como secreto
Terminal sypnia token create --project shop --name "CI source maps" --scopes adminEn Sypnia Cloud también puedes crearlo en la app. Copia el valor
sps_…en los secretos de tu CI comoSYPNIA_API_TOKEN. En GitHub: Settings del repositorio, luego Secrets and variables, luego Actions.Deberías verUn secreto llamadoSYPNIA_API_TOKENen tu CI. El token no está en el repositorio.Agrega la subida al flujo de trabajo
Sypnia Cloud
.github/workflows/deploy.yml name: Deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # la subida lee los commits desde la versión anterior - uses: actions/setup-node@v4 with: node-version: 22 - run: npm ci - name: Name the release run: echo "RELEASE=$(git rev-parse --short HEAD)" >> "$GITHUB_ENV" - run: npm run build - name: Upload source maps to Sypnia run: npx sypnia sourcemaps upload dist --release "$RELEASE" --delete-after env: SYPNIA_API_TOKEN: ${{ secrets.SYPNIA_API_TOKEN }} - name: Deploy run: npm run deployAlojamiento propio
.github/workflows/deploy.yml name: Deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # la subida lee los commits desde la versión anterior - uses: actions/setup-node@v4 with: node-version: 22 - run: npm ci - name: Name the release run: echo "RELEASE=$(git rev-parse --short HEAD)" >> "$GITHUB_ENV" - run: npm run build - name: Upload source maps to Sypnia run: npx sypnia sourcemaps upload dist --release "$RELEASE" --delete-after env: SYPNIA_API_TOKEN: ${{ secrets.SYPNIA_API_TOKEN }} SYPNIA_BASE_URL: https://sypnia.example.com - name: Deploy run: npm run deployDeberías verText release 4f2a91c (production), previous 9c1e7b2: 1 commit, 2 files changed found 42 JavaScript files with a source map uploaded 41 maps (6.2 MB), skipped 1 already there deleted 42 .map files from dist done in 3.4 s
Qué necesita saber el comando
| Opción | Cuándo la necesitas |
|---|---|
<directory> | La salida de la compilación: dist, build, .output/public. |
--release | Siempre. El mismo texto que release en init. |
--url-prefix | Cuando el directorio no se sirve desde la raíz de tu sitio. Con dist/assets/a.js servido como /static/assets/a.js, pasa --url-prefix /static. |
--environment | Cuando el despliegue no es de producción: --environment staging. |
--delete-after | Casi siempre: quita los archivos .map para que no se publiquen. |
--allow-failure | Cuando un despliegue nunca debe esperar a Sypnia. El comando imprime el error y termina con 0; las pilas de esa versión quedan sin traducir. |
--patches | Para enviar además el diff de cada archivo cambiado, lo que afina el análisis. Los diffs son tu código fuente y van al proveedor de IA junto con el análisis. |
--dry-run | Para ver qué se enviaría. |
Cada opción está en la referencia del CLI. Fuera de GitHub Actions las mismas tres líneas sirven en cualquier parte: nombrar la versión, compilar, subir.
Qué agrega registrar la versión
El mismo comando registra la versión con lo que git sabe: el commit, los commits desde la versión anterior y los archivos que cambiaron. Eso es lo que le permite a un problema decir «desde el cambio de ayer» y nombrar el cambio. En Sypnia Cloud con la GitHub App instalada, el agente además puede leer por su cuenta la diferencia entre los dos commits. Mira Versiones y source maps.
Comprueba que funcionó
curl "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
-H "Authorization: Bearer $SYPNIA_API_TOKEN""uploaded": true, y url_path igual a la ruta desde la que tu sitio lo sirve, como /assets/checkout-3f9c.js.Luego mira la siguiente ocurrencia de cualquier problema de esa versión: su pila dice src/checkout/checkout.tsx:142 en vez de checkout-3f9c.js:1:48211. Si no, la tabla de Solución de problemas lista las causas; la más común es un nombre de versión que difiere en unos pocos caracteres.
Sin el CLI
La subida son dos llamadas a la API: pedir los enlaces de subida, y luego hacer PUT de cada source map. Úsalas desde un sistema de compilación que no pueda correr el comando. Mira Versiones y source maps en la referencia de la API.