Source Maps and Releases

In production, AdonisJS applications run compiled JavaScript located in the build/ directory. By associating errors with a specific release and uploading source maps to Sentry, your Sentry dashboard will display original TypeScript filenames and line numbers instead of minified build artifacts.

Setting the Release Identifier

Define the SENTRY_RELEASE environment variable in your production environment. A common practice is using the Git commit SHA or a release tag:

SENTRY_RELEASE=a8f42d87e1a3d90f230234

In automated CI/CD pipelines (e.g. GitHub Actions), you can set this dynamically:

export SENTRY_RELEASE=${GITHUB_SHA}

The default config/sentry.ts stub automatically passes env.get('SENTRY_RELEASE') to Sentry:

export default defineConfig({
  // ...
  release: env.get('SENTRY_RELEASE'),
});

Generating Source Maps

Ensure that TypeScript emits source maps during the build by checking your tsconfig.json:

{
  "compilerOptions": {
    "sourceMap": true
  }
}

When you build your application using node ace build, source map files (.js.map) will be emitted alongside compiled JavaScript files in the build/ folder.

Uploading Source Maps via Sentry CLI

Install @sentry/cli as a development dependency or run it via npx:

npm install --save-dev @sentry/cli

Authentication Environment Variables

Set the required Sentry CLI authentication variables in your CI/CD runner:

• SENTRY_AUTH_TOKEN: Sentry user or internal integration authentication token.
• SENTRY_ORG: Your Sentry organization slug.
• SENTRY_PROJECT: Your Sentry project slug.

Upload Script

Add a deployment or build step that uploads the generated source maps:

# 1. Build the AdonisJS application
node ace build

# 2. Upload source maps for the current release
npx @sentry/cli sourcemaps upload \
  --release="${SENTRY_RELEASE}" \
  ./build

# 3. (Optional) Delete .map files if you prefer not to include them in production docker images
find ./build -name "*.map" -type f -delete