Official Sentry SDK for Nuxt (BETA)

This SDK is in Beta. The API is stable but updates may include minor changes in behavior. Please reach out on GitHub if you have any feedback or concerns. This SDK is for Nuxt. If you're using Vue see our Vue SDK here.

Links

• Official Nuxt SDK Docs

Compatibility

The minimum supported version of Nuxt is 3.0.0.

General

This package is a wrapper around @sentry/node for the server and @sentry/vue for the client side, with added functionality related to Nuxt.

Limitations:

• Server monitoring is not available during development mode (nuxt dev)

Manual Setup

1. Prerequisites & Installation

1. Install the Sentry Nuxt SDK:

   # Using npm
   npm install @sentry/nuxt
   
   # Using yarn
   yarn add @sentry/nuxt
   

2. Nuxt Module Setup

The Sentry Nuxt SDK is based on Nuxt Modules.

1. Add @sentry/nuxt/module to the modules section of nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@sentry/nuxt/module'],
});

3. Client-side setup

Add a sentry.client.config.ts file to the root of your project:

import { useRuntimeConfig } from '#imports';
import * as Sentry from '@sentry/nuxt';

Sentry.init({
  // If set up, you can use your runtime config here
  dsn: useRuntimeConfig().public.sentry.dsn,
});

4. Server-side setup

Add a sentry.server.config.ts file to the root of your project:

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

// Only run `init` when process.env.SENTRY_DSN is available.
if (process.env.SENTRY_DSN) {
  Sentry.init({
    dsn: 'your-dsn',
  });
}

Using useRuntimeConfig does not work in the Sentry server config file due to technical reasons (the file has to be loaded before Nuxt is loaded). To be able to use process.env you either have to add --env-file=.env to your node command

node --env-file=.env .output/server/index.mjs

or use the dotenv package:

import dotenv from 'dotenv';
import * as Sentry from '@sentry/nuxt';

dotenv.config();

Sentry.init({
  dsn: process.env.SENTRY_DSN,
});

Uploading Source Maps

To upload source maps, you have to enable client source maps in your nuxt.config.ts. Then, you add your project settings to the sentry.sourceMapsUploadOptions of your nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  sourcemap: { client: true },

  modules: ['@sentry/nuxt/module'],
  sentry: {
    sourceMapsUploadOptions: {
      org: 'your-org-slug',
      project: 'your-project-slug',
      authToken: process.env.SENTRY_AUTH_TOKEN,
    },
  },
});

Troubleshooting

When adding sentry.server.config.ts, you might get an error like this: "Failed to register ESM hook import-in-the-middle/hook.mjs". You can add an override (npm/pnpm) or a resolution (yarn) for @vercel/nft to fix this. This will add the hook.mjs file to your build output (Nitro issue here).

For npm:

"overrides": {
  "@vercel/nft": "^0.27.4"
}

for yarn:

"resolutions": {
  "@vercel/nft": "^0.27.4"
}

or for pnpm:

"pnpm": {
  "overrides": {
    "@vercel/nft": "^0.27.4"
  }
}