Upload Source Maps with the CLI

The @abrova-trace/cli uploads sourcemaps from your CI/CD pipeline to Abrova Trace. Any error captured after the upload will be shown with real source file names and line numbers in the dashboard — no more minified 4d240bf7.js:1:16945 stacks.

1Prerequisites#

You need three things:

• Node.js 18+ on the machine that runs the upload (your CI runner or local dev machine)
• A personal access token with the sourcemaps:write scope
• Your project DSN from Trace → Source maps & symbols in Abrova Console

2Install the CLI#

The CLI comes from Abrova Center. Add the registry once, then install it as a dev dependency:

# .npmrc (in your project root)
@abrova-trace:registry=https://center.abrova.ir/api/packages/abrova/npm/

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

Run it from your project with npx abrova-trace (for example npx abrova-trace --help). The command name is abrova-trace.

3Create a Personal Access Token#

Personal Access Tokens (PATs) are user-scoped, long-lived credentials — the same pattern many developer CLIs use. They replace user session tokens for automated workflows.

1. Open the Abrova Console: Account → Personal Access Tokens
2. Click New Token
3. Give it a name (e.g. CI upload — production)
4. Enable the sourcemaps:write scope
5. Choose an expiration (no expiration is fine for CI; 90 days is a common compromise)
6. Click Create Token
7. Copy the ab_pat_xxx value immediately — it will only be shown once

Store this in your CI environment as a secret named ABROVA_TRACE_TOKEN.

4Find Your Project ID#

The CLI's "project ID" is the project DSN of the web platform the maps belong to (each platform of an Abrova project has its own DSN).

1. Open Abrova Console and select your project
2. Go to Trace → Source maps & symbols (the Source maps tab)
3. 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 this as ABROVA_TRACE_PROJECT in your CI environment (the CLI also still reads the legacy ABROVA_TRACE_DSN variable).

5Upload from CI#

Add these two lines to your build pipeline right after your production build creates the sourcemap files:

export ABROVA_TRACE_TOKEN=ab_pat_xxx
export ABROVA_TRACE_PROJECT=<your-project-id>

npx abrova-trace sourcemaps upload ./path/to/your/sourcemaps \
  --release "1.2.3"

That's it. The CLI recursively finds every .map file under the given directory, uploads them all in a single request, and tags them with the release version so Abrova Trace can match them to errors from that version.

6Example: Upload Next.js Source Maps#

For Next.js, enable sourcemap generation in next.config.js:

module.exports = {
  productionBrowserSourceMaps: true,
};

Then in your CI script:

#!/bin/bash
set -e

# 1. Build with sourcemaps
npm run build

# 2. Copy sourcemaps into a dedicated folder
mkdir -p ./sourcemaps
find .next/static/chunks -name "*.js.map" -exec cp {} ./sourcemaps \;

# 3. Upload to Abrova Trace tagged with the release version
npx abrova-trace sourcemaps upload \
  --release "$NEXT_PUBLIC_APP_VERSION" \
  ./sourcemaps

# 4. Remove sourcemaps from the deployed build so browsers can't download them
#    (source stays private — Abrova keeps the maps server-side)
find .next/static/chunks -name "*.js.map" -delete
find .next/static/chunks -name "*.js" -exec \
  sed -i '/^\/\/# sourceMappingURL=/d' {} +

7Match the Release Version#

The --release flag must match the version your SDK sends when reporting errors. If your Next.js SDK is initialised with:

AbrovaTrace.init({
  apiKey: process.env.NEXT_PUBLIC_ABROVA_TRACE_API_KEY!,
  release: process.env.NEXT_PUBLIC_APP_VERSION, // e.g. "1.2.3"
});

Then upload with:

npx abrova-trace sourcemaps upload \
  --release "$NEXT_PUBLIC_APP_VERSION" \
  ./sourcemaps

If the release strings don't match, Abrova Trace won't find the sourcemap for the error and will fall back to showing the minified stack.

8CLI Options#

A flag takes precedence over its environment variable. A project API key (ab_live_…) does not work here — the CLI needs a personal access token.

9Self-Hosted Abrova Trace#

When you run Abrova Trace on your own infrastructure, point the CLI at your API:

export ABROVA_TRACE_API_URL=https://trace.mycompany.com

npx abrova-trace sourcemaps upload \
  --release "1.2.3" \
  ./sourcemaps

The CLI does exactly the same thing against a self-hosted instance — no code changes, just the URL.

10Exit Codes#

• 0 — success
• 1 — any error (invalid token, network failure, upload rejected, etc.)

Suitable for gating a deploy on successful upload:

# .github/workflows/deploy.yml
- name: Upload sourcemaps
  run: npx abrova-trace sourcemaps upload --release "$GITHUB_SHA" ./sourcemaps
  env:
    ABROVA_TRACE_TOKEN: ${{ secrets.ABROVA_TRACE_TOKEN }}
    ABROVA_TRACE_PROJECT: ${{ secrets.ABROVA_TRACE_PROJECT }}

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

11Upload Limits#

• Max bundle size: 110 MB per upload (whole multipart request)
• Max file size: 50 MB per individual .map file
• Max files per upload: 500

These are generous defaults that fit typical Next.js, Vite, and webpack builds. Larger files are rejected with HTTP 413. If your bundle exceeds 110 MB, split it into several uploads with the same --release (for example one folder at a time), or contact us.

12iOS dSYMs#

The CLI uploads JavaScript source maps only. iOS debug symbols (dSYMs) are uploaded in Abrova Console:

1. In Xcode, open Organizer › Archives › Download Debug Symbols, then zip the .dSYM folder
2. Open Trace → Source maps & symbols and choose the iOS dSYMs tab
3. Pick the release and drop the .zip file (one .zip per upload, up to 10 MB)

Uploading needs the member role or higher; deleting uploaded files needs admin or owner — see Roles & Permissions.

13Troubleshooting#