Manual Setup

If you can't (or prefer not to) run the automatic setup, you can follow the instructions below to configure the Sentry Nuxt SDK in your application. This guide is also useful to adjust the pre-set configuration if you used the installation wizard for automatic setup.

Compatibility

The Sentry Nuxt SDK supports Nuxt version 3.7.0 and above. For best results, we recommend using Nuxt 3.14.0 or later, which includes updated dependencies critical to the SDK's functionality.

In case you are using Nuxt before version 3.14.0, add the following overrides:

"overrides": {
  "ofetch": "^1.4.0",
  "@vercel/nft": "^0.27.4"
}

Install

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 the Nuxt runtime config here
  // dsn: useRuntimeConfig().public.sentry.dsn, // modify, depending on your custom runtime config
  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

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

Load Sentry config

Sentry can only be loaded on the server-side by being explicitly added via --import.

Check out the --import CLI flag docs for setup instructions.

Troubleshoot Errors during Server Startup

In case you are experiencing problems after adding sentry.server.config.ts and building the project, you can check out Troubleshooting or read through the different installation methods.

Source Maps Upload

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",
    },
  },
});

The Sentry Nuxt Module automatically enables source map generation for your project, but you'll need to enable it explicitly for the client-side. Add this code to your Nuxt configuration:

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

The 'hidden' option functions the same as true, by enabling source map generation, but it also suppresses the source map reference comments that would normally appear at the end of each generated file in the build output. This keeps the source maps available without exposing their references in the files.

When you open browser developer tools, browsers try to fetch source maps using reference comments in bundled files. If source maps are uploaded to Sentry and removed from the client-side, these references cause 404 errors in developer tools. The 'hidden' option stops these comments from being generated, preventing browsers from trying to fetch missing files and avoiding unnecessary errors.

You need to explicitly enable client-side source maps because Nuxt applies default source map settings, and the Sentry Nuxt Module respects these 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.

Server-side

Sentry can only be loaded on the server-side by being explicitly added via --import. Check out the --import CLI flag docs for setup instructions.

To verify that Sentry works on the server-side, add the following snippet on the server-side:

export default defineEventHandler(event => {
  throw new Error("Sentry Example API Route Error");
});

If you want to test server-side monitoring locally, build your project and run:

# Start your app after building your project with `nuxi build`
node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs

Client-side

Add the following snippet on the client-side:

<script setup>
  import * as Sentry from "@sentry/nuxt";

  function triggerClientError() {
    throw new Error("Nuxt Button Error");
  }

  function getSentryData() {
    Sentry.startSpan(
      {
        name: "Example Frontend Span",
        op: "test",
      },
      async () => {
        await $fetch("/api/sentry-example");
      },
    );
  }
</script>

<template>
  <button id="errorBtn" @click="triggerClientError">
    Throw Client Error
  </button>
  <button type="button" @click="getSentryData">Throw Server 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
• In case you experience any issues during setup or startup, check out Troubleshooting or read through the different installation methods.