Docs

Source maps in CI

Upload source maps and register the release from your build, with a complete GitHub Actions example, so stacks show your own files and problems say which change started them.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. The three rules
  2. Set it up
  3. Make the build write source maps, and know its release
  4. Create the token and store it as a secret
  5. Add the upload to the workflow
  6. What the command needs to know
  7. What registering the release adds
  8. Check that it worked
  9. Without the CLI

This guide is for whoever owns the build. It works the same for Sypnia Cloud and for a self-hosted engine; only one variable differs. For a Next.js app you do not need it: @sypnia/next uploads source maps during next build, see Next.js.

At the end you will have: every deploy registered as a release with its commit, its source maps stored privately in Sypnia, and no .map file published with your site.

You need: a project, a build that can write source maps, and an API token with the admin scope.

The three rules

  1. One name for the release. The string you pass to init as release and the string you upload for must be identical. Use the short git commit for both.
  2. Upload after bundling, before deploying. The maps must be in Sypnia before the first visitor loads the new code.
  3. Never publish the maps. They contain your source code. The upload command deletes them from the build output.

Set it up

  1. Make the build write source maps, and know its release

    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 (or external) writes the .map files without a comment in the JavaScript that points at them.

    You should see
    After RELEASE=4f2a91c npm run build, dist holds .js files and a .map next to each.
  2. Create the token and store it as a secret

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

    On Sypnia Cloud you can also create it in the app. Copy the sps_… value into your CI’s secrets as SYPNIA_API_TOKEN. In GitHub: the repository’s Settings, then Secrets and variables, then Actions.

    You should see
    A secret named SYPNIA_API_TOKEN in your CI. The token is not in the repository.
  3. Add the upload to the workflow

    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   # the upload reads the commits since the previous release
    
          - 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
    You should see
    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

What the command needs to know

FlagWhen you need it
<directory>The build output: dist, build, .output/public.
--releaseAlways. The same string as release in init.
--url-prefixWhen the directory is not served from the root of your site. With dist/assets/a.js served as /static/assets/a.js, pass --url-prefix /static.
--environmentWhen the deploy is not production: --environment staging.
--delete-afterAlmost always: it removes the .map files so they are not published.
--allow-failureWhen a deploy must never wait for Sypnia. The command then prints the error and exits 0; that release’s stacks stay minified.
--patchesTo also send each changed file’s diff, which makes the analysis sharper. The diffs are your source code and go to the AI provider with the analysis.
--dry-runTo see what would be sent.

Every flag is in the CLI reference. Outside GitHub Actions the same three lines work anywhere: name the release, build, upload.

What registering the release adds

The same command registers the release with what git knows: the commit, the commits since the previous release and the files they changed. That is what lets a problem say «since yesterday’s change» and name the change. On Sypnia Cloud with the GitHub App installed, the agent can also read the difference between the two commits itself. See Releases and source maps.

Check that it worked

Terminal
curl "https://api.sypnia.com/v1/releases/4f2a91c/sourcemaps" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
You should see
Each file with "uploaded": true, and url_path equal to the path your site serves it from, such as /assets/checkout-3f9c.js.

Then look at the next occurrence of any problem in that release: its stack reads src/checkout/checkout.tsx:142 instead of checkout-3f9c.js:1:48211. If it does not, the table in Troubleshooting lists the causes, most often a release name that differs by a few characters.

Without the CLI

The upload is two API calls: ask for upload links, then PUT each map. Use them from a build system that cannot run the command. See Releases and source maps in the API reference.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close