feat(nuxt): Add "Deployment Provider Setup"

docs/platforms/javascript/common/best-practices/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: Special Use Cases
 description: "Learn how to set up Sentry for several specific use cases with these best practice guides."
-sidebar_order: 6
+sidebar_order: 7
 notSupported:
   - javascript.node
   - javascript.aws-lambda

docs/platforms/javascript/common/data-management/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: Data Management
 description: Learn about different ways to scrub data within your SDK before it gets sent to Sentry.
-sidebar_order: 7
+sidebar_order: 8
 ---
 
 <PageGrid />

docs/platforms/javascript/common/deployment-provider-setup/general.mdx

@@ -0,0 +1,97 @@
+---
+title: General
+sidebar_order: 1
+description: "Learn about the general deployment setup when using Sentry."
+supported:
+  - javascript.nuxt
+---
+
+<PlatformSection supported={['javascript.nuxt']}>
+  Nuxt compiles all your code for the client and server side to ECMAScript modules (ESM) syntax ([learn more about ESM and Nuxt](https://nuxt.com/docs/guide/concepts/esm)).
+</PlatformSection>
+
+Adding Sentry on the server-side for a project in ESM syntax is different from adding Sentry to a project in CommonJS (CJS) syntax.
+The Sentry initialization code needs to be loaded first when the application starts.
+Preloading the Sentry server config file can be done with the Node [`--import`](https://nodejs.org/api/cli.html#--importmodule) CLI flag when starting the application.
+
+Internally, Sentry uses a specific ESM loader hook "[import-in-the-middle/hook.mjs](https://www.npmjs.com/package/import-in-the-middle)" which is
+automatically added when you add the Sentry server-side config file with `--import`. This will automatically instrument all modules in your application.
+
+## Setup Sentry Server Config
+
+As described above, there are some prerequisites for adding Sentry to a Nuxt project in ESM syntax:
+
+1. The possibility to add the node `--import` CLI flag.
+2. Knowing the correct path to your Sentry server config file within your deployment environment (to add the path to the `--import` CLI flag).
+3. The `hook.mjs` file is available under `node_modules/import-in-the-middle/hook.mjs` wherever your server-side code is executed.
+4. Running Node.js version 18.19.0 or higher (support for `--import`).
+
+### Adding the `--import` CLI flag
+
+You can either add the flag directly to the `node` command when starting the application:
+
+```bash
+node --import ./path/to/sentry-server-config.mjs ./path/to/index.mjs
+```
+
+or use the `NODE_OPTIONS` environment variable:
+
+```bash
+NODE_OPTIONS="--import ./path/to/sentry-server-config.mjs" node ./path/to/index.mjs
+```
+
+If modifying the `node` command is not possible, you can also add the `NODE_OPTIONS` environment variable wherever you can set environment variables within your deployment environment.
+Make sure that this variable is only available during server runtime (not during build time).
+
+### `import-in-the-middle/hook.mjs` is available
+
+Usually, the file `node_modules/import-in-the-middle/hook.mjs` is automatically available when installing dependencies.
+However, some deployment providers use custom node bundlers that might not include all `node_modules` in order to save storage.
+This is often done by tracing the node files and only including the necessary dependencies. Since Sentry has to include the `hook.mjs` file internally with `module.register()` it might not be discovered by some bundlers and therefore not included.
+If you get a warning that the `hook.mjs` file is not found, please report this in [the Sentry JS GitHub repo](https://github.com/getsentry/sentry-javascript/issues) or file an issue at your deployment provider.
+
+Nitro (which is used by Nuxt and SolidStart on the server side) uses [`@vercel/nft`](https://github.com/vercel/nft) during the build. `@vercel/nft` includes files that are added with `module.register()` from version 0.27.4 onwards.
+In case you get a runtime error along the lines `Cannot find module '/node_modules/import-in-the-middle/hook.mjs'`, make sure to add a resolution (yarn) or an override (npm/pnpm) for `@vercel/nft`:
+
+```json {tabTitle:yarn} {filename: package.json}
+{
+  "resolutions": {
+    "@vercel/nft": "^0.27.4"
+  }
+}
+```
+
+```json {tabTitle:npm/pnpm} {filename: package.json}
+{
+  "overrides": {
+    "@vercel/nft": "^0.27.4"
+  }
+}
+```
+
+## Setup other environment variables
+
+In case you are using environment variables in your project to set up Sentry don't forget to also add them inside your deployment environment:
+
+```bash
+SENTRY_DSN="___PUBLIC_DSN___"
+SENTRY_AUTH_TOKEN="___ORG_AUTH_TOKEN___"
+```
+
+
+
+## Exclude modules from import-in-the-middle
+
+As all packages are wrapped under the hood by [import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle), you might run into issues with certain packages. If you run into a problem with a package, you can skip instrumentation for it by configuring `registerEsmLoaderHooks` in your `Sentry.init()` config.
+
+```javascript {tabTitle:ESM} {filename: instrument.mjs}
+import * as Sentry from "@sentry/node";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  registerEsmLoaderHooks: {
+    // Provide a list of package names to exclude from instrumentation
+    exclude: ["package-name"],
+  },
+});
+```

docs/platforms/javascript/common/deployment-provider-setup/index.mdx

@@ -0,0 +1,9 @@
+---
+title: Deployment Provider Setup
+sidebar_order: 4
+description: "Review our alternate installation methods."
+supported:
+  - javascript.nuxt
+---
+
+<PageGrid />

docs/platforms/javascript/common/deployment-provider-setup/netlify.mdx

@@ -0,0 +1,50 @@
+---
+title: Netlify
+sidebar_order: 10
+description: "Learn about running Sentry when deploying to Netlify."
+supported:
+  - javascript.nuxt
+---
+
+<Alert level="warning">
+  Deploying on Netlify is still experimental. Currently, not all Sentry features are supported on the server-side. Only your frontend will be monitored.
+</Alert>
+
+<Alert level="info">
+  Before approaching the steps below, read the general documentation around <PlatformLink to="/deployment-provider-setup/general/">setting up Sentry on a deployment provider</PlatformLink> to get quick general overview of the process.
+  This page only shows Netlify-specific steps.
+</Alert>
+
+## Approach 1: Adding the `--import` flag
+
+<PlatformSection supported={['javascript.nuxt']}>
+  The server-side of Nuxt is deployed as a Netlify Function. So make sure to scope the environment variable `NODE_OPTIONS` to "Functions".
+  The path to the function is depending on your setup. When building the preset locally, the file is available at: `.netlify/functions-internal/server/sentry.server.config.mjs`.
+
+  <Alert level="warning">
+    The docs for this are still vague and we will update them as soon as we know more about which exact path to use for the `--import` flag.
+  </Alert>
+
+  <Include name="common-imgs/netlify-env-variable" />
+</PlatformSection>
+
+
+## Approach 2: Enable `experimental_basicServerTracing`
+
+
+Enabling `experimental_basicServerTracing` can be used when adding the node option `--import` does not work. This however only comes with limited tracing functionality because Sentry server config is not **pre**loaded with `--import`.
+
+<PlatformSection supported={['javascript.nuxt']}>
+  Enabling this option will automatically import the Sentry server config at the top of the server entry file (server entry: `.netlify/functions-internal/server/server.mjs`).
+
+  ```javascript {tabTitle: Nuxt Config} {filename: nuxt.config.ts}
+    export default defineNuxtConfig({
+      sentry: {
+        // ... other options
+        experimental_basicServerTracing: true
+      },
+    })
+  ```
+</PlatformSection>
+
+

docs/platforms/javascript/common/enriching-events/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: Enriching Events
 description: Add additional context to your events to make them easier to debug.
-sidebar_order: 5
+sidebar_order: 6
 ---
 
 <PageGrid />

docs/platforms/javascript/common/usage/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: Capturing Errors and Events
 description: "Learn how to use the SDK to manually capture errors and other events."
-sidebar_order: 4
+sidebar_order: 5
 ---
 
 Sentry's SDK hooks into your runtime environment and automatically reports errors, uncaught exceptions, and unhandled rejections as well as other types of errors depending on the platform.

docs/platforms/javascript/guides/nuxt/features/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: Vue Features
 description: "Learn how to exposes features for first class integration with Vue with Sentry's Nuxt SDK."
-sidebar_order: 4
+sidebar_order: 5
 ---
 
 The Sentry Nuxt SDK offers Vue-specific features for first class integration with the framework.

includes/common-imgs/netlify-env-variable.md

@@ -0,0 +1 @@
+![Setting up scoped environment variables in Netlify](./img/netlify-env-variable.png)