create quick start guide for Nuxt manual setup

inventarSarah · inventarSarah · commit f4e13d65bcb8 · 2025-04-10T10:59:20.000+02:00
diff --git a/docs/platforms/javascript/guides/nuxt/manual-setup.mdx b/docs/platforms/javascript/guides/nuxt/manual-setup.mdx
@@ -1,17 +1,25 @@
 ---
 title: Manual Setup
 sidebar_order: 1
-description: "Learn how to set up the SDK manually."
+description: "Learn how to manually set up Sentry in your Nuxt app and capture your first errors."
 ---
 
-If you can't (or prefer not to) run the <PlatformLink to="/#install">automatic setup</PlatformLink>, 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.
+<Alert type="info">
+  For the fastest setup, we recommend using the [wizard
+  installer](/platforms/javascript/guides/nuxt).
+</Alert>
 
-## Compatibility
+<Alert level="warning">
+  This SDK is currently in **beta**. Beta features are still in progress and may
+  have bugs. Please reach out on
+  [GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if
+  you have any feedback or concerns.
+</Alert>
 
-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.
+<PlatformContent includePath="getting-started-prerequisites" />
 
-In case you are using Nuxt before version `3.14.0`, add the following overrides:
+<Expandable title="Are you using Nuxt version < 3.14.0?">
+Add the following overrides:
 
 ```json {tabTitle:npm} {filename:package.json}
 "overrides": {
@@ -36,7 +44,21 @@ In case you are using Nuxt before version `3.14.0`, add the following overrides:
 }
 ```
 
-## Install
+</Expandable>
+
+## Step 1: Install
+
+Choose the features you want to configure, and this guide will show you how:
+
+<OnboardingOptionButtons
+  options={["error-monitoring", "performance", "session-replay"]}
+/>
+
+<PlatformContent includePath="getting-started-features-expandable" />
+
+### Install the Sentry SDK
+
+Run the command for your preferred package manager to add the Sentry SDK to your application:
 
 ```bash {tabTitle:npm}
 npm install @sentry/nuxt --save
@@ -50,66 +72,90 @@ yarn add @sentry/nuxt
 pnpm add @sentry/nuxt
 ```
 
-## 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`
+## Step 2: Configure
 
-In these files, you can specify the full range of <PlatformLink to="/configuration/options">Sentry SDK options</PlatformLink>.
+### Apply Instrumentation to Your App
 
-
-### Nuxt Module Setup
-
-Add the Sentry Nuxt Module to your `nuxt.config.ts` file:
+Add the Sentry Nuxt module to your `nuxt.config.ts` file:
 
 ```javascript {filename:nuxt.config.ts}
 export default defineNuxtConfig({
-  modules: ["@sentry/nuxt/module"]
+  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
+### Configure Client-side Sentry
 
 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:
 
-```javascript {filename:sentry.client.config.ts}
-import * as Sentry from '@sentry/nuxt';
+```javascript {filename:sentry.client.config.ts} {"onboardingOptions": {"performance": "9-15", "session-replay": "7-8, 16-22"}}
+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: "___PUBLIC_DSN___",
+  // Replay may only be enabled for the client-side
+  integrations: [Sentry.replayIntegration()],
+
+  // 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,
+
+  // 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,
+});
+```
 
-  // We recommend adjusting this value in production, or using tracesSampler
-  // for finer control
-  tracesSampleRate: 1.0
+We recommend you store your Sentry [Data Source Name](/concepts/key-terms/dsn-explainer/) (DSN) in an environment variable and configure it via the Nuxt runtime config like so:
+
+```javascript {filename: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
+      },
+    },
+  },
 });
 ```
 
-### Server-side Setup
+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:
+### Configure Server-side Sentry
+
+Add a `sentry.server.config.ts` file to the root of your project and add the following initialization code to it:
 
 ```javascript {filename:sentry.server.config.ts}
-import * as Sentry from '@sentry/nuxt';
+import * as Sentry from "@sentry/nuxt";
 
 Sentry.init({
   dsn: "___PUBLIC_DSN___",
 
-  // We recommend adjusting this value in production, or using tracesSampler
-  // for finer control
-  tracesSampleRate: 1.0
+  // 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,
 });
 ```
 
-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
+We recommend you store your Sentry [Data Source Name](/concepts/key-terms/dsn-explainer/) (DSN) in an environment variable.
+
+<Expandable title="How to access environment variables in sentry.server.config.ts">
+Since Sentry on the server side needs to be loaded before `useRuntimeConfig()` is fully available, environment variables are not directly accessible via `process.env`. To make sure your environment variables are available, use one of these methods:
+
+Load environment variables from your `.env` file when starting the server:
 
 ```bash {tabTitle: node}
 node --env-file=.env .output/server/index.mjs
@@ -118,29 +164,32 @@ node --env-file=.env .output/server/index.mjs
 or use the `dotenv` package:
 
 ```javascript {tabTitle: Server Config} {filename:sentry.server.config.ts} {1,3}
-import dotenv from 'dotenv';
+import dotenv from "dotenv";
 
 dotenv.config();
 
 // ... rest of the file
 ```
 
-#### Load Sentry config
+</Expandable>
+
+**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:
 
-Sentry can only be loaded on the server-side by being explicitly added via `--import`.
+```
+# 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 <PlatformLink to="/install/cli-import">`--import` CLI flag</PlatformLink> docs for setup instructions.
 
 <Alert level="warning">
-  In the beta state of the Nuxt SDK, some features may not work with certain deployment providers. Check the progress on GitHub: [Compatibility with different Deployment Platforms](https://github.com/getsentry/sentry-javascript/issues/14029)
+  In the beta state of the Nuxt SDK, some features may not work with certain
+  deployment providers. Check the progress on GitHub: [Compatibility with
+  different Deployment
+  Platforms](https://github.com/getsentry/sentry-javascript/issues/14029)
 </Alert>
 
-#### 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 <PlatformLink to="/troubleshooting">Troubleshooting</PlatformLink>
-or read through the different <PlatformLink to="/install">installation methods</PlatformLink>.
-
-## Source Maps Upload
+## Step 3: Add Readable Stack Traces With Source Maps (Optional)
 
 The Sentry Nuxt Module uses the [Sentry Vite Plugin](https://www.npmjs.com/package/@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.
@@ -149,7 +198,8 @@ To upload source maps, specify your Sentry auth token as well as your org and pr
 inside the `sentry` options of your `nuxt.config.ts`.
 
 <Alert>
-  The module options inside `sentry` are only affecting the **build-time** of the SDK.
+  The module options inside `sentry` are only affecting the **build-time** of
+  the SDK.
 </Alert>
 
 <OrgAuthTokenNote />
@@ -161,9 +211,9 @@ export default defineNuxtConfig({
     sourceMapsUploadOptions: {
       org: "___ORG_SLUG___",
       project: "___PROJECT_SLUG___",
-      authToken: "___ORG_AUTH_TOKEN___"
-    }
-  }
+      authToken: "___ORG_AUTH_TOKEN___",
+    },
+  },
 });
 ```
 
@@ -172,7 +222,7 @@ but you'll need to enable it explicitly for the client-side. Add this code to yo
 
 ```javascript {filename:nuxt.config.ts} {2}
 export default defineNuxtConfig({
-    sourcemap: { client: 'hidden' }
+  sourcemap: { client: "hidden" },
 });
 ```
 
@@ -186,81 +236,107 @@ 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](https://nuxt.com/docs/api/nuxt-config#sourcemap), and
 the Sentry Nuxt Module respects these when they are explicitly defined.
 
-## Verify
+## Step 4: Verify Your Setup
 
-This snippet includes an intentional error, so you can test that everything is working as soon as you set it up.
+Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.
 
-### Server-side
+### Issues
 
-Sentry can only be loaded on the server-side by being explicitly added via `--import`.
-Check out the <PlatformLink to="/install/cli-import">`--import` CLI flag</PlatformLink> docs for setup instructions.
+To verify that Sentry captures errors and creates issues in your Sentry project, create a test page with a button:
 
-To verify that Sentry works on the server-side, add the following snippet on the server-side:
+```html {tabTitle:Vue} {filename:pages/example-error.vue}
+<script setup>
+  import * as Sentry from "@sentry/nuxt";
 
-```js {tabTitle:Nitro} {filename:server/api/sentry-example.get.ts}
-export default defineEventHandler(event => {
-  throw new Error("Sentry Example API Route Error");
-});
+  function triggerClientError() {
+    throw new Error("Nuxt Button Error");
+  }
+</script>
+
+<template>
+  <button id="errorBtn" @click="triggerClientError">Throw Client Error</button>
+</template>
 ```
 
-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
-  ```
+<OnboardingOption optionId="performance" hideForThisOption>
+  Open the page in a browser (for most Nuxt applications, this will be at
+  localhost) and click the button to trigger a frontend error.
+</OnboardingOption>
 
-<Alert level="warning">
-  Sentry server-side monitoring **doesn't work in development mode!**
+<PlatformContent includePath="getting-started-browser-sandbox-warning" />
 
-  If you experience any issues with the server-side setup, check out <PlatformLink to="/troubleshooting">Troubleshooting</PlatformLink>
-  or read through the different <PlatformLink to="/install">installation methods</PlatformLink>.
-</Alert>
+<OnboardingOption optionId="performance">
+### Tracing
 
-### Client-side
+To test tracing, create a test API route `server/api/sentry-example.get.ts`:
 
-Add the following snippet on the client-side:
+```js {tabTitle:Nitro} {filename: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:
 
 ```html {tabTitle:Vue} {filename:pages/example-error.vue}
 <script setup>
-  import * as Sentry from '@sentry/nuxt';
+  import * as Sentry from "@sentry/nuxt";
 
   function triggerClientError() {
     throw new Error("Nuxt Button Error");
-  };
+  }
 
   function getSentryData() {
     Sentry.startSpan(
       {
-        name: 'Example Frontend Span',
-        op: 'test'
+        name: "Example Frontend Span",
+        op: "test",
       },
       async () => {
-        await $fetch('/api/sentry-example');
+        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>
+  <button id="errorBtn" @click="triggerClientError">Throw Client Error</button>
+  <button type="button" @click="getSentryData">Throw Server Error</button>
 </template>
 ```
 
-<Alert>
+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 it via `--import`.
 
-  Learn more about manually capturing an error or message in our <PlatformLink to="/usage/">Usage documentation</PlatformLink>.
+After running your project:
 
-</Alert>
+1. Open your test page in a browser (for most Nuxt applications, this will be at localhost)
+2. Click the "Throw Client Error" button to trigger an error in the frontend
+3. 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.
+
+</OnboardingOption>
 
-To view and resolve the recorded error, log into [sentry.io](https://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.
+### View Captured Data in Sentry
+
+Now, head over to your project on [Sentry.io](https://sentry.io) to view the collected data (it takes a couple of moments for the data to appear).
+
+<PlatformContent includePath="getting-started-verify-locate-data" />
 
 ## Next Steps
 
-- Track your Vue Components or your Pinia store by [adding support for client features](/platforms/javascript/guides/nuxt/features/)
-- In case you experience any issues during setup or startup, check out <PlatformLink to="/troubleshooting">Troubleshooting</PlatformLink>
-or read through the different <PlatformLink to="/install">installation methods</PlatformLink>.
+At this point, you should have integrated Sentry into your Next.js 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](/platforms/javascript/guides/nuxt/usage/)
+- Continue to [customize your configuration](/platforms/javascript/guides/nuxt/configuration/)
+- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts
+- Learn how to [track your Vue components or your Pinia store](/platforms/javascript/guides/nuxt/features/)
+
+<Expandable permalink={false} title="Are you having problems setting up the SDK?">
+
+- If you encountered issues with setting up Sentry manually, [try our installation wizard](/platforms/javascript/guides/nuxt/)
+- Find various support topics in <PlatformLink to="/troubleshooting">troubleshooting</PlatformLink>
+- [Get support](https://sentry.zendesk.com/hc/en-us/)
+
+</Expandable>
