diff --git a/docs/platforms/javascript/common/install/esm-without-import.mdx b/docs/platforms/javascript/common/install/esm-without-import.mdx index c068fbf1e4586..ae9c0275263fb 100644 --- a/docs/platforms/javascript/common/install/esm-without-import.mdx +++ b/docs/platforms/javascript/common/install/esm-without-import.mdx @@ -21,8 +21,7 @@ When running your application in ESM mode, you will most likely want to This installation method has fundamental restrictions: - - It only supports limited performance instrumentation. - - Only basic `http` instrumentation will work. + - Only basic `http` and `fetch` instrumentation will work. - No DB or framework-specific instrumentation will be available. We recommend using this only if the `--import` flag is not an option for you. diff --git a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx index 2f9358de56f7e..2f6b1a623e5d5 100644 --- a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx @@ -6,18 +6,19 @@ description: "Learn how to use the node --import CLI flag." ## Understanding the `--import` CLI Flag -The [`--import` CLI flag](https://nodejs.org/api/cli.html#--importmodule) in Node is the default way in ESM to preload a module before the application starts. -If you cannot use the SDK's default dynamic import behaviour, setting -this flag is crucial for ensuring proper server-side initialization, as Sentry needs to be initialized before the rest of the application runs. +The [`--import` CLI flag](https://nodejs.org/api/cli.html#--importmodule) in Node is the default way in ESM to preload a specified module at startup. +Setting this CLI flag is crucial for ensuring proper server-side initialization, as Sentry needs to be initialized before the application runs. +This will register Sentry's [loader hook](https://nodejs.org/api/module.html#customization-hooks) and therefore enable proper instrumentation of ESM modules. ## Scenarios where `--import` does not work -- You're not able to add Node CLI flags or environment variables that are scoped to the function runtime -- **Netlify** only allows scoped environment variables on its paid plans at this time -- **Vercel** doesn't currently provide an option for scoping environment variables +- You're unable to add Node CLI flags or environment variables scoped to the function runtime, meaning these variables aren't applied in other scopes, such as build time. +- You don't know the path to the Nuxt server folder in the build output +- At this time, it isn't possible to properly configure `--import` in **Netlify**. +- At this time, it isn't possible to properly configure `--import` in **Vercel**. If any of those points apply to you, you cannot use the `--import` flag to initialize Sentry on the server-side. -Check out the guide for using a top-level import or a dynamic import instead. +Check out the guide for using limited server tracing instead. ## Initializing Sentry with `--import` diff --git a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx index bd5b4cf9d5e70..8a09ed9890077 100644 --- a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx @@ -6,37 +6,18 @@ description: "Learn about how the Nuxt SDK leverages dynamic input() in the buil ## Understanding the `import()` expression -The `import()` expression (also called "dynamic import") allows conditional and flexible module loading in ESM. -For the Sentry Nuxt SDK, it provides an approach to initialize server-side configuration before application startup. + + This installation method doesn't work with more recent versions of Nuxt/Nitro. -The Sentry Nuxt SDK will be initialized before any other code runs and the Nitro server runtime code will be loaded later because of `import()`ing it. -This early initialization is required to set up the SDK's instrumentation of various libraries correctly. + We recommend reading the guide for installing the SDK with the CLI flag `--import` or limited server tracing + -## Initializing Sentry with Dynamic `import()` - -Enable the dynamic `import()` by setting `autoInjectServerSentry`: - -```typescript {filename:nuxt.config.ts} {3} -export default defineNuxtConfig({ - sentry: { - autoInjectServerSentry: 'experimental_dynamic-import' - }, -}) -``` +The `import()` expression, or dynamic import, enables flexible, conditional module loading in ESM. +Node.js will generate a separate module graph for any code wrapped in a dynamic `import()`. This separate graph is evaluated **after** all modules, which are statically `import`ed. -After setting this, the Sentry Nuxt SDK adds some build-time configuration to ensure your app is wrapped with `import()`. -With this, Sentry can be initialized before all other modules of the application. - -The Nuxt server entry file will look something like this: - -```javascript {filename:.output/server/index.mjs} -// Note: The file may have some imports and code, related to debug IDs -Sentry.init({ - dsn: "..." -}); - -import('./chunks/nitro/nitro.mjs').then(function (n) { return n.r; }); -``` +By using the Sentry Nuxt SDK, the server-side application will be wrapped in a dynamic `import()`, while the Sentry configuration will be imported with a static `import`. +This makes it possible to initialize the Sentry Nuxt SDK at startup, while the Nitro server runtime loads later because it is `import()`ed. +This early initialization of Sentry is required to correctly set up the SDK's instrumentation of various libraries. ## Scenarios where `import()` doesn't work @@ -67,7 +48,33 @@ As a temporary workaround, you can add the following overrides in your applicati } ``` -You can also check out the guide for installing the SDK with a CLI flag `--import` or a top-level import. +You can also check out the guide for installing the SDK with the CLI flag `--import` or limited-server-tracing. + +## Initializing Sentry with Dynamic `import()` + +Enable the dynamic `import()` by setting `autoInjectServerSentry`: + +```typescript {filename:nuxt.config.ts} {3} +export default defineNuxtConfig({ + sentry: { + autoInjectServerSentry: 'experimental_dynamic-import' + }, +}) +``` + +After setting this, the Sentry Nuxt SDK will add build-time configuration so that your app will be wrapped with `import()`, +ensuring that Sentry can be initialized before any other modules. + +The Nuxt server entry file will look something like this: + +```javascript {filename:.output/server/index.mjs} +// Note: The file may have some imports and code, related to debug IDs +Sentry.init({ + dsn: "..." +}); + +import('./chunks/nitro/nitro.mjs').then(function (n) { return n.r; }); +``` ## Re-exporting serverless handler functions diff --git a/docs/platforms/javascript/guides/nuxt/install/top-level-import.mdx b/docs/platforms/javascript/guides/nuxt/install/limited-server-tracing.mdx similarity index 53% rename from docs/platforms/javascript/guides/nuxt/install/top-level-import.mdx rename to docs/platforms/javascript/guides/nuxt/install/limited-server-tracing.mdx index b07b2d5acd008..3fe9901214fb1 100644 --- a/docs/platforms/javascript/guides/nuxt/install/top-level-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/limited-server-tracing.mdx @@ -1,20 +1,21 @@ --- -title: Top-level import +title: Limited Server Tracing sidebar_order: 2 -description: "Learn about how the Nuxt SDK adds a top-level import to the build output." +description: "Learn how to set up the Nuxt SDK with limited server tracing by adding a top-level import to the build output." --- -## Understanding Top-level `import` +## Understanding Limited Server Tracing -Sentry needs to be initialized before the application starts. -If the default way of adding an `--import` CLI flag flag does not work for you, -set up the SDK for adding a top-level `import`. This will import the Sentry server-side config at the top of the Nuxt server entry file. +Sentry needs to be initialized before the rest of the application runs. +If the default way of adding an `--import` CLI flag doesn't work for you, +enable the SDK to add a top-level `import`. + +The automatically added top-level `import` will then import the Sentry server-side config at the top of the Nuxt server entry file. In this case, Sentry isn’t initialized before the app starts, but is set up as early as possible. This installation method has fundamental restrictions: - - It only supports limited performance instrumentation. - - Only basic `http` instrumentation will work. + - Only basic `http` and `fetch` instrumentation will work. - No DB or framework-specific instrumentation will be available. We recommend using this only if the `--import` flag is not an option for you. @@ -33,10 +34,4 @@ export default defineNuxtConfig({ ``` By default, the SDK will add the Sentry server config to the build output (typically, `.output/server/sentry.server.config.mjs`). - -With the top-level `import`, the Nuxt server entry file will look something like this: - -```javascript {filename:.output/server/index.mjs} -import './sentry.server.config.mjs'; -// Note: The file may have some imports and code, related to debug IDs -``` +The SDK will then automatically import this file at the top of the Nitro server entry file in the build output. diff --git a/platform-includes/getting-started-verify/javascript.nuxt.mdx b/platform-includes/getting-started-verify/javascript.nuxt.mdx index d1a917fe678e4..f2e4541895698 100644 --- a/platform-includes/getting-started-verify/javascript.nuxt.mdx +++ b/platform-includes/getting-started-verify/javascript.nuxt.mdx @@ -1,4 +1,35 @@ -On the client-side: +### 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: + +```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"); +}); + +``` + +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 + ``` + + + Sentry server-side monitoring **doesn't work in development mode!** + + If you experience any issues with the server-side setup, check out Troubleshooting + or read through the different installation methods. + + +### Client-side + +Add the following snippet on the client-side: ```html {tabTitle:Vue} {filename:pages/example-error.vue}