Manual Setup
Learn how to manually set up Sentry in your Nuxt app and capture your first errors.
For the fastest setup, we recommend using the wizard installer.
This SDK is currently in beta. Beta features are still in progress and may have bugs. Please reach out on GitHub if you have any feedback or concerns.
You need:
- A Sentry account and project
- Your application up and running
- Nuxt version
3.7.0
or above (3.14.0
+ recommended)
Choose the features you want to configure, and this guide will show you how:
Run the command for your preferred package manager to add the Sentry SDK to your application:
npm install @sentry/nuxt --save
Add the Sentry Nuxt module to your nuxt.config.ts
file:
nuxt.config.ts
export default defineNuxtConfig({
modules: ["@sentry/nuxt/module"],
});
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:
sentry.client.config.ts
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",
// Adds request headers and IP for users, for more info visit:
// https://docs.sentry.io/platforms/javascript/guides/nuxt/configuration/options/#sendDefaultPii
sendDefaultPii: true,
// session-replay
// Replay may only be enabled for the client-side
integrations: [Sentry.replayIntegration()],
// session-replay
// 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/configuration/options/#traces-sample-rate
tracesSampleRate: 1.0,
// performance
// session-replay
// Capture Replay for 10% of all sessions,
// plus for 100% of sessions with an error
// Learn more at
// https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration
replaysSessionSampleRate: 0.1,
replaysOnErrorSampleRate: 1.0,
// session-replay
});
We recommend you store your Sentry Data Source Name (DSN) in an environment variable and configure it via the Nuxt runtime config like so:
nuxt.config.ts
export default defineNuxtConfig({
modules: ["@sentry/nuxt"],
runtimeConfig: {
public: {
sentry: {
dsn: process.env.SENTRY_DSN_PUBLIC, // Use a public environment variable for the DSN
},
},
},
});
This allows you to access the DSN using useRuntimeConfig().public.sentry.dsn
.
Add a sentry.server.config.ts
file to the root of your project and add the following initialization code to it:
sentry.server.config.ts
import * as Sentry from "@sentry/nuxt";
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
// 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/configuration/options/#traces-sample-rate
tracesSampleRate: 1.0,
// performance
});
We recommend you store your Sentry Data Source Name (DSN) in an environment variable.
Sentry's server-side monitoring doesn't work in development mode. To enable it, you first need to build your application and then load the Sentry server-side config using the --import
flag when running your application:
# Start your app after building your project with `nuxi build`
node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs
Check out the --import
CLI flag docs for setup instructions.
To upload source maps for clear error stack traces, add your Sentry auth token, organization, and project slugs in the sentry.sourceMapsUploadOptions
inside your configuration file:
nuxt.config.ts
export default defineNuxtConfig({
modules: ["@sentry/nuxt/module"],
sentry: {
sourceMapsUploadOptions: {
org: "example-org",
project: "example-project",
authToken: "sntrys_YOUR_TOKEN_HERE",
},
},
});
sentry
options only affect the build time of the SDK.While Nuxt generates source maps on the server side by default, you need to explicitly enable client-side source maps in your Nuxt configuration:
nuxt.config.ts
export default defineNuxtConfig({
sourcemap: { client: "hidden" },
});
The hidden
option enables source map generation while preventing source map reference comments that would normally appear at the end of each generated file in the build output.
Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.
To verify that Sentry captures errors and creates issues in your Sentry project, create a test page with a button:
pages/example-error.vue
<script setup>
import * as Sentry from "@sentry/nuxt";
function triggerClientError() {
throw new Error("Nuxt Button Error");
}
</script>
<template>
<button id="errorBtn" @click="triggerClientError">
Throw Client Error
</button>
</template>
Open the page in a browser (for most Nuxt applications, this will be at localhost:3000) and click the button to trigger a frontend error.
Important
Errors triggered from within your browser's developer tools (like the browser console) are sandboxed, so they will not trigger Sentry's error monitoring.
To test tracing, create a test API route server/api/sentry-example.get.ts
:
server/api/sentry-example.get.ts
export default defineEventHandler((event) => {
throw new Error("Sentry Example API Route Error");
});
Then update the test page by including a new button that executes a function to fetch your API route:
pages/example-error.vue
<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>
Once you have your test code in place, you need to build your project since Sentry's server-side monitoring doesn't work in development mode. Then start your app and make sure to load Sentry on the server side by explicitly adding the Sentry server config in the build output via --import
.
After running your project:
- Open your test page in a browser (for most Nuxt applications, this will be at localhost:3000)
- Click the "Throw Client Error" button to trigger an error in the frontend
- Click the "Throw Server Error" button to trigger an error within the API route and start a performance trace to measure the time it takes for the API request to complete.
Now, head over to your project on Sentry.io to view the collected data (it takes a couple of moments for the data to appear).
At this point, you should have integrated Sentry into your Nuxt application and should already be sending data to your Sentry project.
Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:
- Learn how to manually capture errors
- Continue to customize your configuration
- Get familiar with Sentry's product features like tracing, insights, and alerts
- Learn how to track your Vue components or your Pinia store
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").