Use Sentry with Nuxt 3

Nuxt 3 has a long way to go (at time of writing) with module support, but you don't need to worry about Sentry. We have it covered!

This tutorial will show you how to use Sentry with Nuxt 3. Why do I need to create this tutorial? Currently, the Sentry module for Nuxt is incompatible with Nuxt v3, but a module isn't necessarily required. Setting up Sentry to work with Nuxt v3 is surprisingly easy.

Set up your environment(s)

To make the most of Sentry, it's convenient to set up different environments for the environments you have (such as "development", "staging", and "production"). By setting up Sentry in this way, you can segregate and filter your errors by environment, useful for debugging purposes. An error in production may not be an error in your staging environment, for example!

To start with, let's add some environments to the package.json file:

{
  // Other config
  "scripts": {
    "dev": "ENV=dev nuxt dev",
    "staging": "ENV=staging nuxt dev",
    "build:dev": "ENV=dev nuxt build",
    "build:staging": "ENV=staging nuxt build",
    "build:prod": "ENV=production nuxt build",
  },
  // Rest of config
}

We're using the ENV environment variable to declare the environment instead of NODE_ENV. Feel free to change it to NODE_ENV if you prefer.

Why so many scripts? I think it's essential to use your development and staging environments locally, so that's why we have a staging script. The build environments are self-explanatory. Add as many build scripts as you need and change the ENV variable.

Now, we need to expose this environment variable within Nuxt itself. To do this, open your nuxt.config.ts file:

import { defineNuxtConfig } from 'nuxt3';

export default defineNuxtConfig({

  // ... other config here

  publicRuntimeConfig: {
    ENV: process.env.ENV
  },

  // ... other config here

})

The above will add our ENV environment variable to Nuxt, allowing us to use it in plugins. Speaking of which...

Create Sentry plugin(s)

Here, we're creating a Sentry plugin specifically for the frontend by naming the file sentry.client.ts. If you want Sentry on the server, you can create another plugin file sentry.server.ts or sentry.ts if you want to send errors from both the frontend and backend. However, this is not recommended.

So, here is the whole plugin:

import { defineNuxtPlugin } from '#app';
import * as pkg from '~/package.json';
import * as Sentry from '@sentry/browser';
import { Integrations } from '@sentry/tracing';

export default defineNuxtPlugin((nuxtApp) => {
  const release = `<your-project-name>@${pkg.version}`;
  const environment = nuxtApp.$config.ENV;

  Sentry.init({
    dsn: '<your-sentry-dsn>',
    release,
    environment,
    integrations: [new Integrations.BrowserTracing()],
    sampleRate: 1,
    tracesSampleRate: 1
  });
});

What's going on here?:

• We're importing everything required for the Sentry integration (including contents of the package.json file).
• Inside the plugin, we're declaring the release with the project name and version defined in package.json.
• We're declaring the environment we configured earlier.
• Finally, in the Sentry init() function, we're using our DSN (from Sentry) to initialise Sentry and include any Integrations.

sampleRate and tracesSampleRate are also defined. These options are unavailable in the Sentry module for Nuxt 2 but are useful when you want to send a percentage of errors to Sentry. In a production environment with many users, you may be happy setting sampleRate to 0.5 to send 50% of the errors, for example. Here are the docs for sampleRate and tracesSampleRate for reference.

What about Integrations?

We're not covering Integrations in this tutorial, but it's possible to add routing to provide a clear picture of your user journey before receiving an error.

Conclusion

And that's a wrap! After creating this simple plugin, I'm not sure the Sentry module is required anymore. Creating a plugin like this takes a few extra minutes, but you can use the entirety of Sentry and not the options exposed in the module.