---
title: "Nitro"
description: "Learn how to set up Sentry in your Nitro app to capture errors and monitor performance."
url: https://docs.sentry.io/platforms/javascript/guides/nitro/
---

# Nitro | Sentry for Nitro

This SDK is currently in **BETA**. Beta features are still in progress and may have bugs. Please reach out on [GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if you have any feedback or concerns.

## [Prerequisites](https://docs.sentry.io/platforms/javascript/guides/nitro.md#prerequisites)

You need:

* A Sentry [account](https://sentry.io/signup/) and [project](https://docs.sentry.io/product/projects.md)
* A Nitro application (`3.0.260415-beta` or newer)
* Node.js 18.19.0+

## [Install](https://docs.sentry.io/platforms/javascript/guides/nitro.md#install)

Choose the features you want to configure, and this guide will show you how:

Error Monitoring\[ ]Tracing\[ ]Logs

Want to learn more about these features?

* [**Issues**](https://docs.sentry.io/product/issues.md) (always enabled)
  <!-- -->
  :
  <!-- -->
  Sentry's core error monitoring product that automatically reports errors, uncaught exceptions, and unhandled rejections. If you have something that looks like an exception, Sentry can capture it.
* [**Tracing**](https://docs.sentry.io/product/tracing.md):
  <!-- -->
  Track software performance while seeing the impact of errors across multiple systems. For example, distributed tracing allows you to follow a request from the frontend to the backend and back.
* [**Profiling**](https://docs.sentry.io/product/explore/profiling.md):
  <!-- -->
  Gain deeper insight than traditional tracing without custom instrumentation, letting you discover slow-to-execute or resource-intensive functions in your app.
* [**Logs**](https://docs.sentry.io/product/explore/logs.md):
  <!-- -->
  Centralize and analyze your application logs to correlate them with errors and performance issues. Search, filter, and visualize log data to understand what's happening in your applications.

### [Install the Sentry SDK](https://docs.sentry.io/platforms/javascript/guides/nitro.md#install-the-sentry-sdk)

Run the command for your preferred package manager to add the Sentry SDK to your application:

```bash
npm install @sentry/nitro --save
```

## [Configure](https://docs.sentry.io/platforms/javascript/guides/nitro.md#configure)

The Nitro SDK is configured in two places: a build-time wrapper that registers a Nitro module, and a runtime file that initializes the SDK before your server starts.

### [Configure the Nitro Build](https://docs.sentry.io/platforms/javascript/guides/nitro.md#configure-the-nitro-build)

Wrap your Nitro config with `withSentryConfig` so the Sentry module is registered during the build. Provide your auth token, organization, and project slugs so that source maps are automatically uploaded during production builds.

`.env`

```bash
SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
```

### [Initialize the Sentry SDK](https://docs.sentry.io/platforms/javascript/guides/nitro.md#initialize-the-sentry-sdk)

Create an `instrument.mjs` file in your project root:

`instrument.mjs`

```javascript
import * as Sentry from "@sentry/nitro";

Sentry.init({
  dsn: "___PUBLIC_DSN___",
  // Adds request headers and IP for users, for more info visit:
  // https://docs.sentry.io/platforms/javascript/guides/nitro/configuration/options/#sendDefaultPii
  sendDefaultPii: true,
  // ___PRODUCT_OPTION_START___ performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/nitro/configuration/options/#tracesSampleRate
  tracesSampleRate: 1.0,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ logs

  // Enable logs to be sent to Sentry
  enableLogs: true,
  // ___PRODUCT_OPTION_END___ logs
});
```

### [Source Maps](https://docs.sentry.io/platforms/javascript/guides/nitro.md#source-maps)

By default, `withSentryConfig` generates hidden source maps, uploads them to Sentry, and deletes the `.map` files after the build. This gives you readable stack traces in Sentry without shipping source maps to production. If you already set `sourcemap` in your Nitro config, the SDK respects your setting.

### [Run Your Application](https://docs.sentry.io/platforms/javascript/guides/nitro.md#run-your-application)

Load the instrumentation file with Node's `--import` flag before any Nitro command. This works for `nitro dev`, `nitro preview`, and your production start script:

`package.json`

```json
{
  "scripts": {
    "dev": "NODE_OPTIONS='--import ./instrument.mjs' nitro dev",
    "preview": "NODE_OPTIONS='--import ./instrument.mjs' nitro preview",
    "start": "NODE_OPTIONS='--import ./instrument.mjs' node .output/server/index.mjs"
  }
}
```

## [Verify Your Setup](https://docs.sentry.io/platforms/javascript/guides/nitro.md#verify-your-setup)

Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.

### [Issues](https://docs.sentry.io/platforms/javascript/guides/nitro.md#issues)

Add a test route that throws an error, then open `/debug-sentry` in your browser (or `curl` it) to trigger the error:

`routes/debug-sentry.ts`

```javascript
import { defineHandler } from "nitro/h3";

export default defineHandler(() => {
  throw new Error("My first Sentry error!");
});
```

### [Tracing](https://docs.sentry.io/platforms/javascript/guides/nitro.md#tracing)

To verify tracing, add a handler that starts a manual span:

`routes/debug-sentry.ts`

```javascript
import { defineHandler } from "nitro/h3";
import * as Sentry from "@sentry/nitro";

export default defineHandler(async () => {
  await Sentry.startSpan(
    {
      op: "test",
      name: "My First Test Transaction",
    },
    async () => {
      await new Promise((resolve) => setTimeout(resolve, 100));
      throw new Error("My first Sentry error!");
    },
  );
});
```

### [Logs NEW](https://docs.sentry.io/platforms/javascript/guides/nitro.md#logs-)

To verify that Sentry catches your logs, add some log statements to your application:

```javascript
Sentry.logger.info("User example action completed");

Sentry.logger.warn("Slow operation detected", {
  operation: "data_fetch",
  duration: 3500,
});

Sentry.logger.error("Validation failed", {
  field: "email",
  reason: "Invalid email",
});
```

### [View Captured Data in Sentry](https://docs.sentry.io/platforms/javascript/guides/nitro.md#view-captured-data-in-sentry)

Finally, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear).

Need help locating the captured errors in your Sentry project?

* Open the
  <!-- -->
  [**Issues**](https://sentry.io/orgredirect/organizations/:orgslug/issues/)
  <!-- -->
  page and select an error from the issues list to view the full details and context of this error. For more details, see this
  <!-- -->
  [interactive walkthrough](https://docs.sentry.io/product/sentry-basics/integrate-frontend/generate-first-error.md#ui-walkthrough).
* Open the
  <!-- -->
  [**Traces**](https://sentry.io/orgredirect/organizations/:orgslug/explore/traces/)
  <!-- -->
  page and select a trace to reveal more information about each span, its duration, and any errors. For an interactive UI walkthrough, click
  <!-- -->
  [here](https://docs.sentry.io/product/sentry-basics/distributed-tracing/generate-first-error.md#ui-walkthrough).
* Open the
  <!-- -->
  [**Profiles**](https://sentry.io/orgredirect/organizations/:orgslug/profiling/)
  <!-- -->
  page, select a transaction, and then a profile ID to view its flame graph. For more information, click
  <!-- -->
  [here](https://docs.sentry.io/product/explore/profiling/profile-details.md).
* Open the
  <!-- -->
  [**Logs**](https://sentry.io/orgredirect/organizations/:orgslug/explore/logs/)
  <!-- -->
  page and filter by service, environment, or search keywords to view log entries from your application. For an interactive UI walkthrough, click
  <!-- -->
  [here](https://docs.sentry.io/product/explore/logs.md#overview).

## [Features](https://docs.sentry.io/platforms/javascript/guides/nitro.md#features)

### [Automatic Error Capturing](https://docs.sentry.io/platforms/javascript/guides/nitro.md#automatic-error-capturing)

The SDK registers a Nitro `error` hook that captures unhandled errors from route handlers and middleware. `HTTPError`s with 3xx or 4xx status codes are skipped.

To disable the built-in error hook, set `enableNitroErrorHandler: false` in `Sentry.init`:

`instrument.mjs`

```javascript
Sentry.init({
  dsn: "___PUBLIC_DSN___",
  enableNitroErrorHandler: false,
});
```

### [Automatic Tracing](https://docs.sentry.io/platforms/javascript/guides/nitro.md#automatic-tracing)

The SDK creates transactions for incoming requests using Nitro's tracing channels (`h3.request` and `srvx.request`). `withSentryConfig` enables `tracingChannel: true` on your Nitro config automatically.

* Root request spans use `op: 'http.server'` with parameterized route names (e.g. `GET /users/:id`)
* Middleware spans use `op: 'middleware.nitro'`
* Path parameters are attached as `url.path.parameter.<key>` attributes
* 3xx/4xx `HTTPError`s do not mark the span as errored

### [Distributed Tracing](https://docs.sentry.io/platforms/javascript/guides/nitro.md#distributed-tracing)

The SDK appends `sentry-trace` and `baggage` values to `Server-Timing` response headers so the browser SDK can link pageload traces to their server trace. Incoming `sentry-trace` and `baggage` headers are honored by the underlying `@sentry/node` SDK. No additional configuration needed.

### [Manual Spans](https://docs.sentry.io/platforms/javascript/guides/nitro.md#manual-spans)

You can create manual spans inside your route handlers:

```javascript
import { defineHandler } from "nitro/h3";
import * as Sentry from "@sentry/nitro";

export default defineHandler(() => {
  return Sentry.startSpan({ name: "process-payment" }, () => {
    // ... your code
  });
});
```

## [Runtime Behavior](https://docs.sentry.io/platforms/javascript/guides/nitro.md#runtime-behavior)

The SDK is a wrapper around `@sentry/node` and re-exports its full API. All Node.js instrumentation from `@sentry/node` (HTTP clients, databases, etc.) works out of the box, and the Nitro-specific tracing channels add parameterized routes and middleware spans on top.

## [Next Steps](https://docs.sentry.io/platforms/javascript/guides/nitro.md#next-steps)

* Explore [practical guides](https://docs.sentry.io/guides.md) on what to monitor, log, track, and investigate after setup
* Learn how to [manually capture errors](https://docs.sentry.io/platforms/javascript/guides/nitro/usage.md)
* Continue to [customize your configuration](https://docs.sentry.io/platforms/javascript/guides/nitro/configuration.md)
* Get familiar with [Sentry's product features](https://docs.sentry.io/product.md) like tracing, insights, and alerts

Are you having problems setting up the SDK?

* Find various topics in [Troubleshooting](https://docs.sentry.io/platforms/javascript/guides/nitro/troubleshooting.md)
* [Get support](https://www.sentry.help/en/)

## Other JavaScript Frameworks

- [Angular](https://docs.sentry.io/platforms/javascript/guides/angular.md)
- [Astro](https://docs.sentry.io/platforms/javascript/guides/astro.md)
- [AWS Lambda](https://docs.sentry.io/platforms/javascript/guides/aws-lambda.md)
- [Azure Functions](https://docs.sentry.io/platforms/javascript/guides/azure-functions.md)
- [Bun](https://docs.sentry.io/platforms/javascript/guides/bun.md)
- [Capacitor](https://docs.sentry.io/platforms/javascript/guides/capacitor.md)
- [Cloud Functions for Firebase](https://docs.sentry.io/platforms/javascript/guides/firebase.md)
- [Cloudflare](https://docs.sentry.io/platforms/javascript/guides/cloudflare.md)
- [Connect](https://docs.sentry.io/platforms/javascript/guides/connect.md)
- [Cordova](https://docs.sentry.io/platforms/javascript/guides/cordova.md)
- [Deno](https://docs.sentry.io/platforms/javascript/guides/deno.md)
- [Effect](https://docs.sentry.io/platforms/javascript/guides/effect.md)
- [Electron](https://docs.sentry.io/platforms/javascript/guides/electron.md)
- [Elysia](https://docs.sentry.io/platforms/javascript/guides/elysia.md)
- [Ember](https://docs.sentry.io/platforms/javascript/guides/ember.md)
- [Express](https://docs.sentry.io/platforms/javascript/guides/express.md)
- [Fastify](https://docs.sentry.io/platforms/javascript/guides/fastify.md)
- [Gatsby](https://docs.sentry.io/platforms/javascript/guides/gatsby.md)
- [Google Cloud Functions](https://docs.sentry.io/platforms/javascript/guides/gcp-functions.md)
- [Hapi](https://docs.sentry.io/platforms/javascript/guides/hapi.md)
- [Hono](https://docs.sentry.io/platforms/javascript/guides/hono.md)
- [Koa](https://docs.sentry.io/platforms/javascript/guides/koa.md)
- [Nest.js](https://docs.sentry.io/platforms/javascript/guides/nestjs.md)
- [Next.js](https://docs.sentry.io/platforms/javascript/guides/nextjs.md)
- [Node.js](https://docs.sentry.io/platforms/javascript/guides/node.md)
- [Nuxt](https://docs.sentry.io/platforms/javascript/guides/nuxt.md)
- [React](https://docs.sentry.io/platforms/javascript/guides/react.md)
- [React Router Framework](https://docs.sentry.io/platforms/javascript/guides/react-router.md)
- [Remix](https://docs.sentry.io/platforms/javascript/guides/remix.md)
- [Solid](https://docs.sentry.io/platforms/javascript/guides/solid.md)
- [SolidStart](https://docs.sentry.io/platforms/javascript/guides/solidstart.md)
- [Svelte](https://docs.sentry.io/platforms/javascript/guides/svelte.md)
- [SvelteKit](https://docs.sentry.io/platforms/javascript/guides/sveltekit.md)
- [TanStack Start React](https://docs.sentry.io/platforms/javascript/guides/tanstackstart-react.md)
- [Vue](https://docs.sentry.io/platforms/javascript/guides/vue.md)
- [Wasm](https://docs.sentry.io/platforms/javascript/guides/wasm.md)

## Topics

- [Installation Methods](https://docs.sentry.io/platforms/javascript/guides/nitro/install.md)
- [Capturing Errors](https://docs.sentry.io/platforms/javascript/guides/nitro/usage.md)
- [Source Maps](https://docs.sentry.io/platforms/javascript/guides/nitro/sourcemaps.md)
- [Logs](https://docs.sentry.io/platforms/javascript/guides/nitro/logs.md)
- [Tracing](https://docs.sentry.io/platforms/javascript/guides/nitro/tracing.md)
- [AI Agent Monitoring](https://docs.sentry.io/platforms/javascript/guides/nitro/ai-agent-monitoring.md)
- [Application Metrics](https://docs.sentry.io/platforms/javascript/guides/nitro/metrics.md)
- [Profiling](https://docs.sentry.io/platforms/javascript/guides/nitro/profiling.md)
- [Crons](https://docs.sentry.io/platforms/javascript/guides/nitro/crons.md)
- [User Feedback](https://docs.sentry.io/platforms/javascript/guides/nitro/user-feedback.md)
- [Sampling](https://docs.sentry.io/platforms/javascript/guides/nitro/sampling.md)
- [Enriching Events](https://docs.sentry.io/platforms/javascript/guides/nitro/enriching-events.md)
- [Extended Configuration](https://docs.sentry.io/platforms/javascript/guides/nitro/configuration.md)
- [OpenTelemetry Support](https://docs.sentry.io/platforms/javascript/guides/nitro/opentelemetry.md)
- [Feature Flags](https://docs.sentry.io/platforms/javascript/guides/nitro/feature-flags.md)
- [Data Management](https://docs.sentry.io/platforms/javascript/guides/nitro/data-management.md)
- [Security Policy Reporting](https://docs.sentry.io/platforms/javascript/guides/nitro/security-policy-reporting.md)
- [Migration Guide](https://docs.sentry.io/platforms/javascript/guides/nitro/migration.md)
- [Troubleshooting](https://docs.sentry.io/platforms/javascript/guides/nitro/troubleshooting.md)