Docs

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 MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Las tres reglas
  2. Configúralo
  3. Haz que la compilación escriba source maps, y que conozca su versión
  4. Crea el token y guárdalo como secreto
  5. Agrega la subida al flujo de trabajo
  6. Qué necesita saber el comando
  7. Qué agrega registrar la versión
  8. Comprueba que funcionó
  9. Sin el CLI

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

  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
    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,
    });

    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

    Terminal
    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
    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
    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ónCuándo la necesitas
<directory>La salida de la compilación: dist, build, .output/public.
--releaseSiempre. El mismo texto que release en init.
--url-prefixCuando 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.
--environmentCuando el despliegue no es de producción: --environment staging.
--delete-afterCasi siempre: quita los archivos .map para que no se publiquen.
--allow-failureCuando 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.
--patchesPara 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-runPara 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ó

Terminal
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 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.

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar