@sentry/astro

Official Sentry SDK for Astro

Links

• Official SDK Docs

SDK Status

This SDK is in Beta and not yet fully stable. If you have feedback or encounter any bugs, feel free to open an issue.

General

This package is a wrapper around @sentry/node for the server and @sentry/browser for the client side.

Installation and Setup

Install the Sentry Astro SDK with the astro CLI:

npx astro add @sentry/astro

Add your DSN and source maps upload configuration:

import { defineConfig } from 'astro/config';
import sentry from '@sentry/astro';

export default defineConfig({
  integrations: [
    sentry({
      dsn: '__DSN__',
      sourceMapsUploadOptions: {
        project: 'your-sentry-project-slug',
        authToken: process.env.SENTRY_AUTH_TOKEN,
      },
    }),
  ],
});

Follow this guide to create an auth token and add it to your environment variables:

SENTRY_AUTH_TOKEN="your-token"

Server Instrumentation

For Astro apps configured for (hybrid) Server Side Rendering (SSR), the Sentry integration will automatically add middleware to your server to instrument incoming requests if you're using Astro 3.5.2 or newer.

If you're using Astro <3.5.2, complete the setup by adding the Sentry middleware to your src/middleware.js file:

// src/middleware.js
import { sequence } from 'astro:middleware';
import * as Sentry from '@sentry/astro';

export const onRequest = sequence(
  Sentry.handleRequest(),
  // Add your other handlers after Sentry.handleRequest()
);

The Sentry middleware enhances the data collected by Sentry on the server side by:

• Enabling distributed tracing between client and server
• Collecting performance spans for incoming requests
• Enhancing captured errors with additional information

Disable Automatic Server Instrumentation

You can opt out of using the automatic sentry server instrumentation in your astro.config.mjs file:

import { defineConfig } from 'astro/config';
import sentry from '@sentry/astro';

export default defineConfig({
  integrations: [
    sentry({
      dsn: '__DSN__',
      autoInstrumentation: {
        requestHandler: false,
      },
    }),
  ],
});

Configuration

Check out our docs for configuring your SDK setup:

• Getting Started
• Manual Setup and Configuration
• Source Maps Upload

Changelog

8.42.0

Important Changes

• feat(react): React Router v7 support (library) (#14513)

  This release adds support for React Router v7 (library mode). Check out the docs on how to set up the integration: Sentry React Router v7 Integration Docs

Deprecations

• feat: Warn about source-map generation (#14533)

  In the next major version of the SDK we will change how source maps are generated when the SDK is added to an application. Currently, the implementation varies a lot between different SDKs and can be difficult to understand. Moving forward, our goal is to turn on source maps for every framework, unless we detect that they are explicitly turned off. Additionally, if we end up enabling source maps, we will emit a log message that we did so.

  With this particular release, we are emitting warnings that source map generation will change in the future and we print instructions on how to prepare for the next major.

• feat(nuxt): Deprecate tracingOptions in favor of vueIntegration (#14530)

  Currently it is possible to configure tracing options in two places in the Sentry Nuxt SDK:

  • In Sentry.init()
  • Inside tracingOptions in Sentry.init()

  For tree-shaking purposes and alignment with the Vue SDK, it is now recommended to instead use the newly exported vueIntegration() and its tracingOptions option to configure tracing options in the Nuxt SDK:

  // sentry.client.config.ts
  import * as Sentry from '@sentry/nuxt';
  
  Sentry.init({
    // ...
    integrations: [
      Sentry.vueIntegration({
        tracingOptions: {
          trackComponents: true,
        },
      }),
    ],
  });
  

Other Changes

• feat(browser-utils): Update web-vitals to v4.2.4 (#14439)
• feat(nuxt): Expose vueIntegration (#14526)
• fix(feedback): Handle css correctly in screenshot mode (#14535)