NOTICE: This package is in beta state and may be subject to breaking changes.

Official Sentry SDK for Nitro

Links

• Official Nitro SDK Docs
• Example Nitro app

Compatibility

The minimum supported version of Nitro is 3.0.260415-beta.

General

This package is a wrapper around @sentry/node with added instrumentation for Nitro's features like:

• HTTP handlers and error capturing.
• Middleware instrumentation. <!-- - [Database instrumentation](https://nitro.build/guide/database). --> <!-- - [KV Storage](https://nitro.build/guide/storage) and [Cache](https://nitro.build/guide/cache) instrumentation. -->

Manual Setup

1. Prerequisites & Installation

1. Install the Sentry Nitro SDK:

   bashCopy

   # Using npm
   npm install @sentry/nitro
   
   # Using yarn
   yarn add @sentry/nitro
   
   # Using pnpm
   pnpm add @sentry/nitro
   

2. Build-Time Nitro Config Setup

1. Import withSentryConfig from @sentry/nitro and call it with your Nitro config.

In nitro.config.ts

If you are using a dedicated nitro.config.ts file, you can import withSentryConfig from @sentry/nitro and call it with your Nitro config.

import { defineNitroConfig } from 'nitro/config';
import { withSentryConfig } from '@sentry/nitro';

const config = defineNitroConfig({
  // ...
});

export default withSentryConfig(config, {
  // Sentry Build Options
});

In vite.config.ts

If you are using Nitro as a Vite plugin, you can import withSentryConfig from @sentry/nitro and call it with your Nitro config.

import { defineConfig } from 'vite';
import { nitro } from 'nitro/vite';
import { withSentryConfig } from '@sentry/nitro';

export default defineConfig({
  plugins: [nitro()],
  nitro: withSentryConfig(
    {
      // Nitro options
    },
    {
      // Sentry Build Options
    },
  ),
});

3. Sentry Config Setup

Create an instrument.mjs file in your project root to initialize the Sentry SDK:

import * as Sentry from '@sentry/nitro';

Sentry.init({
  dsn: '__YOUR_DSN__',
  tracesSampleRate: 1.0,
});

Then use --import in NODE_OPTIONS to load the instrumentation before your app code:

NODE_OPTIONS='--import ./instrument.mjs' npx nitro dev

This works with any Nitro command (nitro dev, nitro preview, or a production start script).

Uploading Source Maps

The withSentryConfig function automatically configures source map uploading when the authToken, org, and project options are provided:

export default withSentryConfig(config, {
  org: 'your-sentry-org',
  project: 'your-sentry-project',
  authToken: process.env.SENTRY_AUTH_TOKEN,
});

Troubleshoot

If you encounter any issues with error tracking or integrations, refer to the official Sentry Nitro SDK documentation. If the documentation does not provide the necessary information, consider opening an issue on GitHub.