# 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ó.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/guides/source-maps-in-ci/

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](https://docs.sypnia.com/es/sdks/nextjs).

**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

1. **Un solo nombre para la versión.** El texto que pasas a `init` como `release` y el texto con el que subes deben ser idénticos. Usa el commit corto de git para ambos.
2. **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.
3. **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

### 1. Haz que la compilación escriba source maps, y que conozca su versión

**Vite**

`vite.config.ts`

```ts
import { defineConfig } from 'vite';

export default defineConfig({
  build: { sourcemap: 'hidden' },
  define: { __RELEASE__: JSON.stringify(process.env.RELEASE ?? '') },
});
```

`src/main.ts`

```ts
import { init } from '@sypnia/browser';

declare const __RELEASE__: string;

init({
  project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e',
  release: __RELEASE__ || undefined,
});
```

**webpack**

`webpack.config.js`

```js
const webpack = require('webpack');

module.exports = {
  devtool: 'hidden-source-map',
  plugins: [new webpack.DefinePlugin({ __RELEASE__: JSON.stringify(process.env.RELEASE ?? '') })],
};
```

**esbuild**

```bash
esbuild src/main.ts --bundle --minify --sourcemap=external --outdir=dist \
  --define:__RELEASE__="\"$RELEASE\""
```

`hidden` (o `external`) escribe los archivos `.map` sin dejar en el JavaScript un comentario que apunte a ellos.

**Deberías ver:**Después de `RELEASE=4f2a91c npm run build`, `dist` tiene archivos `.js` y un `.map` junto a cada uno.

### 2. Crea el token y guárdalo como secreto

```bash
sypnia token create --project shop --name "CI source maps" --scopes admin
```

En Sypnia Cloud también puedes crearlo en la app. Copia el valor `sps_…` en los secretos de tu CI como `SYPNIA_API_TOKEN`. En GitHub: **Settings** del repositorio, luego **Secrets and variables**, luego **Actions**.

**Deberías ver:**Un secreto llamado `SYPNIA_API_TOKEN` en tu CI. El token no está en el repositorio.

### 3. Agrega la subida al flujo de trabajo

**Sypnia Cloud**

`.github/workflows/deploy.yml`

```yaml
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 deploy
```

**Alojamiento propio**

`.github/workflows/deploy.yml`

```yaml
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 deploy
```

**Deberías ver:**

```text
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](https://docs.sypnia.com/es/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](https://docs.sypnia.com/es/concepts/releases-and-source-maps).

## Comprueba que funcionó

```bash
curl "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Deberías ver:**Cada archivo con `"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](https://docs.sypnia.com/es/sdks/troubleshooting) 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](https://docs.sypnia.com/es/api/releases-and-source-maps) en la referencia de la API.
