آپلود source map نکست از CI

A production Next.js build is minified, so without source maps every browser error in Abrova Trace points at something like 4d240bf7.js:1:16945. In this guide your CI uploads the maps of each build to Abrova Trace, tagged with the release, and removes them from what you deploy. Errors from that release then show your own .tsx files and lines.

1Send the release from the SDK#

The CLI tags the maps with a release, and Trace pairs an error with the maps of the release the SDK sent. So the SDK must know the release at build time. Use a NEXT_PUBLIC_ variable: Next.js writes it into the browser bundle during next build.

// app/providers.tsx
'use client';

import { useEffect } from 'react';
import { AbrovaTrace } from '@abrova-trace/nextjs-sdk';

export function Providers({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    AbrovaTrace.init({
      apiKey: process.env.NEXT_PUBLIC_ABROVA_TRACE_API_KEY!, // ab_live_…
      release: process.env.NEXT_PUBLIC_APP_VERSION,           // e.g. "2.3.1"
    });
  }, []);

  return <>{children}</>;
}

If the SDK is not installed yet, follow the Next.js SDK page first (the registry line in .npmrc, then npm install @abrova-trace/nextjs-sdk).

2Turn on browser source maps#

// next.config.js
module.exports = {
  productionBrowserSourceMaps: true,
};

After next build, the .map files sit next to the chunks under .next/static/.

3Install the CLI from Abrova Center#

Add the registry for the @abrova-trace scope once, in .npmrc in your project root (commit this file, so CI reads it too):

# .npmrc
@abrova-trace:registry=https://center.abrova.ir/api/packages/abrova/npm/

Then install the CLI as a dev dependency:

npm install --save-dev @abrova-trace/cli

Run it with npx abrova-trace. It needs Node.js 18 or newer on the machine that runs the upload.

4Create the token and copy the project id#

The CLI does not take your project key. It needs two values:

1. A personal access token. In Abrova Console open Account → Personal Access Tokens, click New Token, name it (for example CI upload, production), turn on the sourcemaps:write scope, and create it. Copy the ab_pat_… value at once; it is shown only once.
2. The project id. Open Trace → Source maps & symbols (the Source maps tab). In the Upload from CI card, pick the web platform if your project has more than one, then copy Project DSN for the CLI.

Store them in your CI as secret variables named ABROVA_TRACE_TOKEN and ABROVA_TRACE_PROJECT. Never commit them.

5Build, upload, then remove the maps#

This script builds, uploads every map under .next/static with the release, and then deletes the maps from the build, so browsers can't download your source. Trace keeps its copy.

#!/bin/bash
# ci/upload-sourcemaps.sh
set -e

export NEXT_PUBLIC_APP_VERSION="${NEXT_PUBLIC_APP_VERSION:?set the release}"

# 1. Build with source maps
npm ci
npm run build

# 2. Upload to Abrova Trace, tagged with the same release the SDK sends
#    (reads ABROVA_TRACE_TOKEN and ABROVA_TRACE_PROJECT from the environment)
npx abrova-trace sourcemaps upload .next/static --release "$NEXT_PUBLIC_APP_VERSION"

# 3. Remove the maps from what you deploy
find .next/static -name "*.js.map" -delete
find .next/static -name "*.js" -exec sed -i '/^\/\/# sourceMappingURL=/d' {} +

The CLI finds every .map file under the folder, uploads them in one request and exits with 0 on success and 1 on any error, so a failed upload stops the job before the deploy. To see what it would send without sending it, add --dry-run.

In GitHub Actions it looks like this:

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Build and upload source maps
        run: bash ci/upload-sourcemaps.sh
        env:
          NEXT_PUBLIC_APP_VERSION: ${{ github.sha }}
          NEXT_PUBLIC_ABROVA_TRACE_API_KEY: ${{ secrets.ABROVA_TRACE_API_KEY }}
          ABROVA_TRACE_TOKEN: ${{ secrets.ABROVA_TRACE_TOKEN }}
          ABROVA_TRACE_PROJECT: ${{ secrets.ABROVA_TRACE_PROJECT }}

      - name: Deploy
        run: ./deploy.sh # runs only if the upload succeeded

The commit hash makes a good release: every build gets its own, and the SDK and the upload always agree. A version number such as 2.3.1 works just as well if you set it in both places.

6Check that it worked#

1. In the CI log, the upload step prints the number of files, the release and project. A 0 exit code means Trace accepted them.
2. In Abrova Console → Trace → Source maps & symbols, the release appears with its files.
3. Deploy, open the site and cause an error in the browser, for example with a test button:

'use client';

export function CrashButton() {
  return (
    <button onClick={() => { throw new Error('Abrova source map test'); }}>
      Crash
    </button>
  );
}

4. Open Trace → Issues and the new issue. The stack trace now shows your file (for example components/CrashButton.tsx) and line, and the issue shows the same release you uploaded.

Remove the test button afterwards.

Troubleshooting#