From 852127cbc08483b048414d2680af60fd3279656b Mon Sep 17 00:00:00 2001 From: s1gr1d Date: Wed, 27 Nov 2024 23:25:12 +0100 Subject: [PATCH 1/4] docs(nuxt): Add Nuxt wizard instructions --- .../javascript.nuxt.mdx | 120 +----------------- .../javascript.nuxt.mdx | 26 ++-- .../javascript.nuxt.mdx | 4 + .../javascript.nuxt.mdx | 38 ++++++ .../javascript.nuxt.mdx | 37 ------ .../javascript.nuxt.mdx | 50 +++++++- 6 files changed, 107 insertions(+), 168 deletions(-) delete mode 100644 platform-includes/getting-started-sourcemaps/javascript.nuxt.mdx diff --git a/platform-includes/getting-started-config/javascript.nuxt.mdx b/platform-includes/getting-started-config/javascript.nuxt.mdx index b19df76547bc7..eac0be07a843f 100644 --- a/platform-includes/getting-started-config/javascript.nuxt.mdx +++ b/platform-includes/getting-started-config/javascript.nuxt.mdx @@ -1,118 +1,2 @@ -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: - -```javascript {filename:nuxt.config.ts} -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: - -```javascript {filename:sentry.client.config.ts} -import * as Sentry from '@sentry/nuxt'; - -Sentry.init({ - // If set up, you can use your runtime config here - // dsn: useRuntimeConfig().public.sentry.dsn, - dsn: "___PUBLIC_DSN___", - - // 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: - -```javascript {filename:sentry.server.config.ts} -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 -}); -``` - -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 - -```bash {tabTitle: node} -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'; - -dotenv.config(); - -// ... rest of the file -``` - - - 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) - - -#### 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](https://github.com/unjs/nitro/issues/2703). - - -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. - -```json {tabTitle:npm} {filename:package.json} -"overrides": { - "@vercel/nft": "^0.27.4" -} -``` - -```json {tabTitle:yarn} {filename:package.json} -"resolutions": { - "@vercel/nft": "^0.27.4" -} -``` - -```json {tabTitle:pnpm} {filename:package.json} -"pnpm": { - "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](https://pnpm.io/next/npmrc#shamefully-hoist)) 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`: - -```json {tabTitle:pnpm} {filename:package.json} -// only when using pnpm -"dependencies": { - "import-in-the-middle": "^1.11.2" -} -``` +To complete your configuration, add options to your `Sentry.init()` calls. +Here, you'll also be able to set context data, which includes data about the user, tags, or even arbitrary data, all of which will be added to every event sent to Sentry. diff --git a/platform-includes/getting-started-install/javascript.nuxt.mdx b/platform-includes/getting-started-install/javascript.nuxt.mdx index de177fd16822d..4225ac74c5cdf 100644 --- a/platform-includes/getting-started-install/javascript.nuxt.mdx +++ b/platform-includes/getting-started-install/javascript.nuxt.mdx @@ -1,11 +1,21 @@ -```bash {tabTitle:npm} -npm install @sentry/nuxt --save -``` +We recommend installing the SDK by running our installation wizard in the root directory of your project: -```bash {tabTitle:yarn} -yarn add @sentry/nuxt +```bash +npx @sentry/wizard@latest -i nuxt ``` -```bash {tabTitle:pnpm} -pnpm add @sentry/nuxt -``` +The wizard will prompt you to log in to Sentry. It will then automatically do the following steps for you: + +- create or update Nuxt files with the default Sentry configuration: + - `sentry.(client|server).config.ts` to initialize the SDK + - `nuxt.config.ts` to add build options to add source maps upload and auto-instrumentation via Vite plugins. +- create a `.env.sentry-build-plugin` file with an auth token to upload source maps (this file is automatically added to `.gitignore`) +- add an example page to your frontend app and your server to verify your Sentry setup + +After the wizard setup is completed, the SDK will automatically capture unhandled errors, and monitor performance. + +You can also manually capture errors. + + + If the setup through the wizard doesn't work for you, you can also set up the SDK manually. + diff --git a/platform-includes/getting-started-next-steps/javascript.nuxt.mdx b/platform-includes/getting-started-next-steps/javascript.nuxt.mdx index bad09ed57a2ee..cc49a6afbc16f 100644 --- a/platform-includes/getting-started-next-steps/javascript.nuxt.mdx +++ b/platform-includes/getting-started-next-steps/javascript.nuxt.mdx @@ -1,3 +1,7 @@ ## 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 Troubleshooting + + +or read through the different installation methods. diff --git a/platform-includes/getting-started-primer/javascript.nuxt.mdx b/platform-includes/getting-started-primer/javascript.nuxt.mdx index 642f9016c0f23..ca0be30e9f8b7 100644 --- a/platform-includes/getting-started-primer/javascript.nuxt.mdx +++ b/platform-includes/getting-started-primer/javascript.nuxt.mdx @@ -2,3 +2,41 @@ 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. + + +Sentry's Nuxt SDK enables automatic reporting of errors and performance data. + +## Compatibility + +The minimum supported Nuxt version is `3.7.0`. + + + We are currently investigating an issue where the server-side is not correctly initialized with a recent update of Nitro (the server-side toolkit in Nuxt). + + We are working on figuring this out ([see issue here](https://github.com/getsentry/sentry-javascript/issues/14514)). For the time being, you can add the following overrides to your application: + +
+ + ```json {tabTitle:npm} {filename:package.json} + "overrides": { + "nitropack": "2.9.7" + "@vercel/nft": "^0.27.4" + } + ``` + + ```json {tabTitle:yarn} {filename:package.json} + "resolutions": { + "nitropack": "2.9.7" + "@vercel/nft": "^0.27.4" + } + ``` + + ```json {tabTitle:pnpm} {filename:package.json} + "pnpm": { + "overrides": { + "nitropack": "2.9.7" + "@vercel/nft": "^0.27.4" + } + } + ``` + diff --git a/platform-includes/getting-started-sourcemaps/javascript.nuxt.mdx b/platform-includes/getting-started-sourcemaps/javascript.nuxt.mdx deleted file mode 100644 index af914e6a290bc..0000000000000 --- a/platform-includes/getting-started-sourcemaps/javascript.nuxt.mdx +++ /dev/null @@ -1,37 +0,0 @@ -## Add Readable Stack Traces to Errors - -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. - -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`. - - - The module options inside `sentry` are only affecting the **build-time** of the SDK. - - - - -```javascript {filename:nuxt.config.ts} {3-9} -export default defineNuxtConfig({ - modules: ["@sentry/nuxt/module"], - sentry: { - sourceMapsUploadOptions: { - org: "___ORG_SLUG___", - project: "___PROJECT_SLUG___", - authToken: "___ORG_AUTH_TOKEN___" - } - } -}); -``` - -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: - -```javascript {filename:nuxt.config.ts} {2} -export default defineNuxtConfig({ - sourcemap: { client: true } -}); -``` - -This step is necessary because Nuxt sets default values for source maps ([Nuxt docs](https://nuxt.com/docs/api/nuxt-config#sourcemap)), and the Sentry Nuxt Module keeps these settings when they are explicitly defined. diff --git a/platform-includes/getting-started-verify/javascript.nuxt.mdx b/platform-includes/getting-started-verify/javascript.nuxt.mdx index 86fc0459d9484..cbdbc663995a3 100644 --- a/platform-includes/getting-started-verify/javascript.nuxt.mdx +++ b/platform-includes/getting-started-verify/javascript.nuxt.mdx @@ -1,14 +1,54 @@ -```html {tabTitle:Vue} {filename:ErrorButton.vue} +On the client-side: + +```html {tabTitle:Vue} {filename:pages/example-error.vue} ``` +On the server-side: + +```js {tabTitle:Nitro} {filename:server/sentry-example-api.ts} +import { defineEventHandler } from '#imports'; + +export default defineEventHandler(event => { + throw new Error("Sentry Example API Route Error"); +}); + +``` + + Keep in mind, that the server-side monitoring **does not work in development mode!** + 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 .output/server/index.mjs + ``` + From 329ac7477b2b0f3543a5a86e5a038f852fbcba14 Mon Sep 17 00:00:00 2001 From: s1gr1d Date: Thu, 28 Nov 2024 14:14:17 +0100 Subject: [PATCH 2/4] update wizard instructions and add troubleshooting item --- .../common/troubleshooting/index.mdx | 49 ++++++++++++++--- .../javascript/guides/nuxt/manual-setup.mdx | 28 +++++++++- .../javascript.nuxt.mdx | 5 +- .../javascript.nuxt.mdx | 53 +++++++++---------- .../javascript.nuxt.mdx | 2 + 5 files changed, 96 insertions(+), 41 deletions(-) diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index 65da2ccbaad77..09064a8a5801e 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -470,21 +470,21 @@ Learn more about fixing these caching issues in the + Nuxt builds the server-side Nitro application as ES Modules, which introduces limitations for server-side tracing during development. + Currently, trace collection is only supported when running the built application, not in development mode (`nuxt dev`). + To collect traces, build your project and run the production build output. + + --- + + We are currently investigating an issue where the server-side is not correctly initialized with a recent update of Nitro (the server-side toolkit in Nuxt). + + We are working on figuring this out ([see issue here](https://github.com/getsentry/sentry-javascript/issues/14514)). For the time being, you can add the following overrides to your application: + + ```json {tabTitle:npm} {filename:package.json} + "overrides": { + "nitropack": "2.9.7" + "@vercel/nft": "^0.27.4" + } + ``` + + ```json {tabTitle:yarn} {filename:package.json} + "resolutions": { + "nitropack": "2.9.7" + "@vercel/nft": "^0.27.4" + } + ``` + + ```json {tabTitle:pnpm} {filename:package.json} + "pnpm": { + "overrides": { + "nitropack": "2.9.7" + "@vercel/nft": "^0.27.4" + } + } + ``` + If you need additional help, you can [ask on GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose). Customers on a paid plan may also contact support. diff --git a/docs/platforms/javascript/guides/nuxt/manual-setup.mdx b/docs/platforms/javascript/guides/nuxt/manual-setup.mdx index edad433089fa8..38510dc269cfc 100644 --- a/docs/platforms/javascript/guides/nuxt/manual-setup.mdx +++ b/docs/platforms/javascript/guides/nuxt/manual-setup.mdx @@ -8,7 +8,33 @@ If you can't (or prefer not to) run the automatic s ## Compatibility -The minimum supported Nuxt version is `3.7.0`. +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: + +```json {tabTitle:npm} {filename:package.json} +"overrides": { + "ofetch": "^1.4.0" + "@vercel/nft": "^0.27.4" +} +``` + +```json {tabTitle:yarn} {filename:package.json} +"resolutions": { + "ofetch": "^1.4.0" + "@vercel/nft": "^0.27.4" +} +``` + +```json {tabTitle:pnpm} {filename:package.json} +"pnpm": { + "overrides": { + "ofetch": "^1.4.0" + "@vercel/nft": "^0.27.4" + } +} +``` ## Install diff --git a/platform-includes/getting-started-next-steps/javascript.nuxt.mdx b/platform-includes/getting-started-next-steps/javascript.nuxt.mdx index cc49a6afbc16f..e95ae48e4656f 100644 --- a/platform-includes/getting-started-next-steps/javascript.nuxt.mdx +++ b/platform-includes/getting-started-next-steps/javascript.nuxt.mdx @@ -1,7 +1,4 @@ ## 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 Troubleshooting - - -or read through the different installation methods. +- In case you experience any issues during setup or startup, check out Troubleshooting. diff --git a/platform-includes/getting-started-primer/javascript.nuxt.mdx b/platform-includes/getting-started-primer/javascript.nuxt.mdx index ca0be30e9f8b7..a620499513311 100644 --- a/platform-includes/getting-started-primer/javascript.nuxt.mdx +++ b/platform-includes/getting-started-primer/javascript.nuxt.mdx @@ -8,35 +8,30 @@ Sentry's Nuxt SDK enables automatic reporting of errors and performance data. ## Compatibility -The minimum supported Nuxt version is `3.7.0`. - - - We are currently investigating an issue where the server-side is not correctly initialized with a recent update of Nitro (the server-side toolkit in Nuxt). - - We are working on figuring this out ([see issue here](https://github.com/getsentry/sentry-javascript/issues/14514)). For the time being, you can add the following overrides to your application: - -
- - ```json {tabTitle:npm} {filename:package.json} +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: + +```json {tabTitle:npm} {filename:package.json} +"overrides": { + "ofetch": "^1.4.0" + "@vercel/nft": "^0.27.4" +} +``` + +```json {tabTitle:yarn} {filename:package.json} +"resolutions": { + "ofetch": "^1.4.0" + "@vercel/nft": "^0.27.4" +} +``` + +```json {tabTitle:pnpm} {filename:package.json} +"pnpm": { "overrides": { - "nitropack": "2.9.7" + "ofetch": "^1.4.0" "@vercel/nft": "^0.27.4" } - ``` - - ```json {tabTitle:yarn} {filename:package.json} - "resolutions": { - "nitropack": "2.9.7" - "@vercel/nft": "^0.27.4" - } - ``` - - ```json {tabTitle:pnpm} {filename:package.json} - "pnpm": { - "overrides": { - "nitropack": "2.9.7" - "@vercel/nft": "^0.27.4" - } - } - ``` - +} +``` diff --git a/platform-includes/getting-started-verify/javascript.nuxt.mdx b/platform-includes/getting-started-verify/javascript.nuxt.mdx index cbdbc663995a3..9dd2a2082be9d 100644 --- a/platform-includes/getting-started-verify/javascript.nuxt.mdx +++ b/platform-includes/getting-started-verify/javascript.nuxt.mdx @@ -51,4 +51,6 @@ export default defineEventHandler(event => { # Start your app after building your project with `nuxi build` node .output/server/index.mjs ``` + + In case you experience any issues with the server-side setup, check out Troubleshooting. From 63c0618fa3491427daee5ce50865e409b875e8b5 Mon Sep 17 00:00:00 2001 From: s1gr1d Date: Fri, 29 Nov 2024 10:17:42 +0100 Subject: [PATCH 3/4] review suggestions --- .../common/troubleshooting/index.mdx | 1 + .../javascript.nuxt.mdx | 2 +- .../javascript.nuxt.mdx | 25 ------------------- .../javascript.nuxt.mdx | 1 + 4 files changed, 3 insertions(+), 26 deletions(-) create mode 100644 platform-includes/getting-started-sourcemaps/javascript.nuxt.mdx diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index 09064a8a5801e..5214704643918 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -506,6 +506,7 @@ Learn more about fixing these caching issues in the Date: Fri, 29 Nov 2024 10:19:34 +0100 Subject: [PATCH 4/4] add link to installation methods --- docs/platforms/javascript/common/troubleshooting/index.mdx | 5 +++-- .../getting-started-next-steps/javascript.nuxt.mdx | 3 ++- platform-includes/getting-started-verify/javascript.nuxt.mdx | 3 ++- 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/platforms/javascript/common/troubleshooting/index.mdx b/docs/platforms/javascript/common/troubleshooting/index.mdx index 5214704643918..633e5d98a24e7 100644 --- a/docs/platforms/javascript/common/troubleshooting/index.mdx +++ b/docs/platforms/javascript/common/troubleshooting/index.mdx @@ -504,10 +504,11 @@ Learn more about fixing these caching issues in the Nuxt builds the server-side Nitro application as ES Modules, which introduces limitations for server-side tracing during development. - Currently, trace collection is only supported when running the built application, not in development mode (`nuxt dev`). - To collect traces, build your project and run the production build output. Currently, trace collection is only supported when building and running the application. Development mode (`nuxt dev`) is currently not supported. + When running the build output, Sentry needs to be initialized before running the rest of the application. This is done automatically, but might not work for your use case. + Read more about this in installation methods. + --- We are currently investigating an issue where the server-side is not correctly initialized with a recent update of Nitro (the server-side toolkit in Nuxt). diff --git a/platform-includes/getting-started-next-steps/javascript.nuxt.mdx b/platform-includes/getting-started-next-steps/javascript.nuxt.mdx index e95ae48e4656f..a7bc3938bc441 100644 --- a/platform-includes/getting-started-next-steps/javascript.nuxt.mdx +++ b/platform-includes/getting-started-next-steps/javascript.nuxt.mdx @@ -1,4 +1,5 @@ ## 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 Troubleshooting. +- In case you experience any issues during setup or startup, check out Troubleshooting +or read through the different installation methods. diff --git a/platform-includes/getting-started-verify/javascript.nuxt.mdx b/platform-includes/getting-started-verify/javascript.nuxt.mdx index 9dd2a2082be9d..d1a917fe678e4 100644 --- a/platform-includes/getting-started-verify/javascript.nuxt.mdx +++ b/platform-includes/getting-started-verify/javascript.nuxt.mdx @@ -52,5 +52,6 @@ export default defineEventHandler(event => { node .output/server/index.mjs ``` - In case you experience any issues with the server-side setup, check out Troubleshooting. + In case you experience any issues with the server-side setup, check out Troubleshooting + or read through the different installation methods.