feat(nuxt): Improve Nuxt server-side setup docs (#12102)

* feat(nuxt): Improve Nuxt server-side setup docs

* review suggestions

Author: s1gr1d

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 <Platfor
 
 <Alert level='warning' title='Restrictions of this installation method'>
   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.

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 <PlatformLink to="/install/dynamic-import/">default dynamic import behaviour</PlatformLink>, 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 <PlatformLink to="/install/top-level-import/">a top-level import</PlatformLink> or a <PlatformLink to="/install/dynamic-import/">dynamic import</PlatformLink> instead.
+Check out the guide for using <PlatformLink to="/install/limited-server-tracing">limited server tracing</PlatformLink> instead.
 
 ## Initializing Sentry with `--import`
 

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.
+<Alert level='warning'>
+  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 <PlatformLink to="/install/cli-import">CLI flag `--import`</PlatformLink> or <PlatformLink to="/install/limited-server-tracing">limited server tracing</PlatformLink>
+</Alert>
 
-## 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 <PlatformLink to="/install/cli-import">CLI flag `--import`</PlatformLink> or a <PlatformLink to="/install/top-level-import/">top-level import</PlatformLink>.
+You can also check out the guide for installing the SDK with the <PlatformLink to="/install/cli-import">CLI flag `--import`</PlatformLink> or <PlatformLink to="/install/limited-server-tracing">limited-server-tracing</PlatformLink>.
+
+## 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
 

docs/platforms/javascript/guides/nuxt/install/top-level-import.mdx renamed to 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 <PlatformLink to="/install/cli-import">`--import` CLI flag</PlatformLink> 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 <PlatformLink to="/install/cli-import">`--import` CLI flag</PlatformLink> 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.
 
 <Alert level='warning' title='Restrictions of this installation method'>
   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.

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 <PlatformLink to="/install/cli-import">`--import` CLI flag</PlatformLink> 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
+  ```
+
+<Alert level="warning">
+  Sentry server-side monitoring **doesn't work in development mode!**
+
+  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>
+
+### Client-side
+
+Add the following snippet on the client-side:
 
 ```html {tabTitle:Vue} {filename:pages/example-error.vue}
 <script setup>
@@ -32,26 +63,4 @@ On the client-side:
 </template>
 ```
 
-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");
-});
 
-```
-
-<Alert level="warning">
-  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
-  ```
-
-  In case 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>

src/middleware.ts

@@ -77,6 +77,10 @@ const USER_DOCS_REDIRECTS: Redirect[] = [
     from: '/platforms/javascript/performance/instrumentation/custom-instrumentation/caches-module/',
     to: '/platforms/javascript/guides/node/performance/instrumentation/custom-instrumentation/caches-module/',
   },
+  {
+    from: '/platforms/javascript/guides/nuxt/install/top-level-import/',
+    to: '/platforms/javascript/guides/nuxt/install/limited-server-tracing/',
+  },
   {
     from: '/account/early-adopter-features/discord/',
     to: '/organization/integrations/notification-incidents/discord/',