Nuxt

Prerequisites

• You need a Sentry account and project

Install

Sentry captures data by using an SDK within your application’s runtime.

npm install @sentry/nuxt --save

Configure

Configuration should happen as early as possible in your application's lifecycle.

To set up the Sentry SDK, register the Sentry Nuxt module and initialize the SDK for client and server. At build time, the Sentry Nuxt Module looks for the following two files:

• Client-Side: sentry.client.config.ts in the root containing Sentry.init
• Server-Side: sentry.server.config.ts in the root containing Sentry.init

In these files, you can specify the full range of Sentry SDK options.

Nuxt Module Setup

Add the Sentry Nuxt Module to your nuxt.config.ts file:

export default defineNuxtConfig({
  modules: ["@sentry/nuxt/module"],
});

Adding this module enables the Sentry SDK in your Nuxt application. The Sentry Nuxt Module will then automatically look for the Sentry configuration files and initialize the SDK accordingly.

Client-side Setup

Add a sentry.client.config.ts file to the root of your project (this is probably the same level as the package.json). In this file, import and initialize Sentry, specifying any SDK options for the client:

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

Sentry.init({
  // If set up, you can use your runtime config here
  // dsn: useRuntimeConfig().public.sentry.dsn,
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  // We recommend adjusting this value in production, or using tracesSampler
  // for finer control
  tracesSampleRate: 1.0,
});

Server-side Setup

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

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

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  // We recommend adjusting this value in production, or using tracesSampler
  // for finer control
  tracesSampleRate: 1.0,
});

The Nuxt useRuntimeConfig() does not work in the Sentry server config due to technical reasons (the config 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";

dotenv.config();

// ... rest of the file

Troubleshoot Errors during Server Startup

After adding sentry.server.config.ts and building the project, 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. See the underlying issue in the UnJS Nitro project.

Nitro updated @vercel/nft in Nitro version 2.10.0, so you might not get this error anymore, and you don't need to add this override/resolution.

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

Pnpm and Import-In-The-Middle

Sentry injects import "import-in-the-middle/hook.mjs" in your server entry. This import acts as a hint for node bundlers to really include this file. As pnpm implements a strict dependency isolation, this import might cause problems. Per default, shamefully-hoist is false (pnpm docs here) and this prevents accessing non-declared dependencies. You probably don't want to change this setting, so you have to explicitly add the dependency import-in-the-middle:

// only when using pnpm
"dependencies": {
  "import-in-the-middle": "^1.11.2"
}

Add Readable Stack Traces to Errors

The Sentry Nuxt Module uses the Sentry Vite Plugin to upload source maps for both server and client builds. This means that when you run a production build (nuxt build), source maps will be generated and uploaded to Sentry, so that you get readable stack traces in your Sentry issues.

To upload source maps, specify your Sentry auth token as well as your org and project slugs. Set them in the sourceMapsUploadOptions option inside the sentry options of your nuxt.config.ts.

export default defineNuxtConfig({
  modules: ["@sentry/nuxt/module"],
  sentry: {
    sourceMapsUploadOptions: {
      org: "example-org",
      project: "example-project",
      authToken: "sntrys_YOUR_TOKEN_HERE",
    },
  },
});

To upload source maps, the Sentry Nuxt Module will automatically enable source map generation in your project if it is not already enabled. However, you need to explicitly enable source map generation on the client-side. To do this, add the following code to your Nuxt configuration:

export default defineNuxtConfig({
  sourcemap: { client: true },
});

This step is necessary because Nuxt sets default values for source maps (Nuxt docs), and the Sentry Nuxt Module keeps these settings when they are explicitly defined.

Verify

This snippet includes an intentional error, so you can test that everything is working as soon as you set it up.

<script setup>
  const triggerError = () => {
    throw new Error("Nuxt Button Error");
  };
</script>

<template>
  <button id="errorBtn" @click="triggerError">Trigger Error</button>
</template>

To view and resolve the recorded error, log into sentry.io and select your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved.

Next Steps

• Track your Vue Components or your Pinia store by adding support for client features