docs(nuxt): Add manual setup and troubleshooting (#11981)

* docs(nuxt): Add manual setup and troubleshooting

* review suggestions

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

@@ -434,26 +434,73 @@ Learn more about fixing these caching issues in the <PlatformLink to="/sourcemap
 
 </PlatformSection>
 
-<Expandable permalink title="pnpm: Resolving 'import-in-the-middle' external package errors">
+<PlatformSection notSupported={['javascript.nuxt']}>
+  <Expandable permalink title="pnpm: Resolving 'import-in-the-middle' external package errors">
 
-When using pnpm, you might encounter errors related to packages that can't be external, particularly with packages like `import-in-the-middle` and `require-in-the-middle`. These errors typically occur due to pnpm's strict dependency management and hoisting behavior.
+  When using pnpm, you might encounter errors related to packages that can't be external, particularly with packages like `import-in-the-middle` and `require-in-the-middle`. These errors typically occur due to pnpm's strict dependency management and hoisting behavior.
 
-While adding these packages as direct dependencies might remove the warning messages, it often doesn't resolve the underlying functionality issues:
+  While adding these packages as direct dependencies might remove the warning messages, it often doesn't resolve the underlying functionality issues:
 
-```bash
-pnpm add import-in-the-middle require-in-the-middle
-```
+  ```bash
+  pnpm add import-in-the-middle require-in-the-middle
+  ```
 
-As a workaround, create or modify `.npmrc` in your project root:
+  As a workaround, create or modify `.npmrc` in your project root:
 
-```npmrc
-shamefully-hoist=true
-```
-<Alert level="warning">
-**Note**: While `shamefully-hoist=true` usually isn't the ideal solution from a dependency management perspective, it's sometimes necessary for compatibility with certain packages that expect Node.js module resolution behavior similar to npm or yarn.
-</Alert>
+  ```npmrc
+  shamefully-hoist=true
+  ```
+  <Alert level="warning">
+  **Note**: While `shamefully-hoist=true` usually isn't the ideal solution from a dependency management perspective, it's sometimes necessary for compatibility with certain packages that expect Node.js module resolution behavior similar to npm or yarn.
+  </Alert>
 
 
-</Expandable>
+  </Expandable>
+</PlatformSection>
+
+<PlatformSection supported={['javascript.nuxt']}>
+  <Expandable title="'import-in-the-middle' error during 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"
+  }
+  }
+    ```
+
+  </Expandable>
+
+  <Expandable permalink title="pnpm: Resolving 'import-in-the-middle' external package errors">
+
+    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`:
+
+    ```bash
+    pnpm add import-in-the-middle
+    ```
+  </Expandable>
+</PlatformSection>
 
 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.

docs/platforms/javascript/guides/nuxt/manual-setup.mdx

@@ -0,0 +1,152 @@
+---
+title: Manual Setup
+sidebar_order: 1
+description: "Learn how to set up the SDK manually."
+---
+
+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 SvelteKit SDK in your application. This guide is also useful to adjust the pre-set configuration if you used the installation wizard for automatic setup.
+
+## Compatibility
+
+The minimum supported Nuxt version is `3.7.0`.
+
+## Install
+
+```bash {tabTitle:npm}
+npm install @sentry/nuxt --save
+```
+
+```bash {tabTitle:yarn}
+yarn add @sentry/nuxt
+```
+
+```bash {tabTitle:pnpm}
+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`
+
+In these files, you can specify the full range of <PlatformLink to="/configuration/options">Sentry SDK options</PlatformLink>.
+
+
+### 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
+
+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
+```
+
+<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)
+</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>.
+
+## Source Maps Upload
+
+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`.
+
+<Alert level="info">
+  The module options inside `sentry` are only affecting the **build-time** of the SDK.
+</Alert>
+
+<OrgAuthTokenNote />
+
+```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.
+
+## Verify
+
+This snippet includes an intentional error, so you can test that everything is working as soon as you set it up.
+
+<PlatformContent includePath="getting-started-verify" />