---
title: Upload Source Maps to Sentry
description: Upload JavaScript source maps to Sentry during Capawesome Cloud native builds — readable stack traces for your Capacitor app, with the auth token stored as a secret.
---

# Sentry

If you monitor your app with [Sentry](https://sentry.io/){:target="_blank"}, uploading source maps during the build turns minified JavaScript stack traces into readable ones. This guide shows how to upload source maps automatically during Capawesome Cloud native builds — with your Sentry auth token stored safely as a secret.

## Prerequisites

- Your app is set up with the [Sentry Capacitor SDK](https://docs.sentry.io/platforms/javascript/guides/capacitor/){:target="_blank"}.
- You have a Sentry auth token. An [organization auth token](https://docs.sentry.io/account/auth-tokens/){:target="_blank"} is recommended — it is pre-scoped for CI tasks like source map uploads.

## Store your Sentry credentials

Add your Sentry credentials to a [custom environment](../environments.md) so they are available during the build. Store the auth token as a **secret** — it is encrypted and never appears in build logs — and the organization and project slugs as regular variables:

=== "CLI"

    ```bash
    npx @capawesome/cli apps:environments:set \
      --variable SENTRY_ORG=your-org-slug \
      --variable SENTRY_PROJECT=your-project-slug \
      --secret SENTRY_AUTH_TOKEN=sntrys_your_token
    ```

=== "Console"

    On the [Environments](https://console.cloud.capawesome.io/apps/_/environments){:target="_blank"} page, choose **Manage environment variables** from the environment's actions menu and add `SENTRY_ORG` and `SENTRY_PROJECT`. Then choose **Manage environment secrets** and add `SENTRY_AUTH_TOKEN`.

`SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` are the standard environment variables that both the Sentry CLI and Sentry's bundler plugins pick up automatically.

Select the environment when you [trigger a build](../builds.md), or [set it as the default environment](../environments.md#set-a-default-environment) so it applies to every build.

## Upload source maps during the build

There are two ways to upload source maps during a build. The bundler plugin is recommended — it hooks into your existing web build, so no build script changes are needed.

### Option 1: Sentry bundler plugin (recommended)

Sentry provides plugins for all common bundlers: [`@sentry/vite-plugin`](https://www.npmjs.com/package/@sentry/vite-plugin){:target="_blank"}, [`@sentry/webpack-plugin`](https://www.npmjs.com/package/@sentry/webpack-plugin){:target="_blank"}, [`@sentry/esbuild-plugin`](https://www.npmjs.com/package/@sentry/esbuild-plugin){:target="_blank"}, and [`@sentry/rollup-plugin`](https://www.npmjs.com/package/@sentry/rollup-plugin){:target="_blank"}. The plugin generates and uploads source maps automatically whenever your web build runs. For Vite:

```js title="vite.config.js"
import { defineConfig } from 'vite';
import { sentryVitePlugin } from '@sentry/vite-plugin';

export default defineConfig({
  build: {
    sourcemap: 'hidden',
  },
  plugins: [
    // The Sentry plugin must be the last plugin.
    sentryVitePlugin({
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
      sourcemaps: {
        filesToDeleteAfterUpload: ['./dist/**/*.map'],
      },
    }),
  ],
});
```

That's it — no changes to your build script are required. During a Capawesome Cloud build, the plugin finds the credentials from your environment and uploads the source maps. In local builds without `SENTRY_AUTH_TOKEN`, the plugin simply skips the upload instead of failing, so your development workflow is unaffected.

The `filesToDeleteAfterUpload` option removes the `.map` files once they are uploaded, so they are not copied into the native app — shipped source maps would increase your app size and expose your source code. Symbolication is unaffected, since Sentry uses the uploaded copies.

### Option 2: Sentry CLI

Alternatively, run the [Sentry CLI](https://docs.sentry.io/platforms/javascript/guides/capacitor/sourcemaps/uploading/){:target="_blank"} after your web build. Since Capawesome Cloud runs the `capawesome:build` script from your `package.json` when present (see [Configure Web Build Script](../web-build-script.md)), chain the upload there:

```json title="package.json"
{
  "scripts": {
    "build": "vite build",
    "capawesome:build": "npm run build && npx @sentry/cli sourcemaps inject dist && npx @sentry/cli sourcemaps upload dist && find dist -name '*.map' -delete"
  }
}
```

Replace `dist` with your web output directory (e.g. `www` or `build`). The `inject` command stamps debug IDs into the built files before they are copied into the native app, so Sentry can match stack traces to the uploaded source maps without any release configuration. The final `find` command removes the `.map` files after the upload so they are not shipped inside your app. Your local `npm run build` stays untouched.

!!! tip "Tag releases with build information"

    You can use the [default variables](../environment-variables.md) to associate the upload with a release, for example `--release $CI_BUILD_ID`. The release name must match the `release` option in your `Sentry.init` configuration. With debug IDs, this is optional — source maps resolve without it.

## Verify the upload

After triggering a build, check the [build logs](../build-logs.md) for the Sentry upload output. In Sentry, the uploaded artifacts appear under your project's **Source Maps** settings — and new errors from the web layer of your app now show readable stack traces.

## Native crash symbolication

Source maps cover the web layer of your app. To also get readable native crash reports, configure Sentry's native tooling in your project — since Capawesome Cloud runs your standard Gradle and Xcode builds, it runs during cloud builds too, using the same `SENTRY_AUTH_TOKEN` secret:

- **Android**: The [Sentry Android Gradle plugin](https://docs.sentry.io/platforms/android/configuration/gradle/){:target="_blank"} uploads ProGuard/R8 mapping files during the Gradle build.
- **iOS**: Upload dSYM files with an [Xcode build phase](https://docs.sentry.io/platforms/apple/guides/ios/dsym/){:target="_blank"}.

## Next steps

- [Set Up Environments](../environments.md) — manage variables and secrets for your builds.
- [Configure Web Build Script](../web-build-script.md) — control which script builds your web assets.
- [Build Logs](../build-logs.md) — inspect the output of your builds.