Skip to content

Commit 1f72538

Browse files
s1gr1ds1gr1d
authored
docs(nuxt): Add manual setup and troubleshooting (#11981)
* docs(nuxt): Add manual setup and troubleshooting * review suggestions
1 parent 6595003 commit 1f72538

File tree

2 files changed

+213
-14
lines changed

2 files changed

+213
-14
lines changed

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

Lines changed: 61 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -434,26 +434,73 @@ Learn more about fixing these caching issues in the <PlatformLink to="/sourcemap
434434
435435
</PlatformSection>
436436
437-
<Expandable permalink title="pnpm: Resolving 'import-in-the-middle' external package errors">
437+
<PlatformSection notSupported={['javascript.nuxt']}>
438+
<Expandable permalink title="pnpm: Resolving 'import-in-the-middle' external package errors">
438439
439-
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.
440+
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.
440441
441-
While adding these packages as direct dependencies might remove the warning messages, it often doesn't resolve the underlying functionality issues:
442+
While adding these packages as direct dependencies might remove the warning messages, it often doesn't resolve the underlying functionality issues:
442443
443-
```bash
444-
pnpm add import-in-the-middle require-in-the-middle
445-
```
444+
```bash
445+
pnpm add import-in-the-middle require-in-the-middle
446+
```
446447
447-
As a workaround, create or modify `.npmrc` in your project root:
448+
As a workaround, create or modify `.npmrc` in your project root:
448449
449-
```npmrc
450-
shamefully-hoist=true
451-
```
452-
<Alert level="warning">
453-
**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.
454-
</Alert>
450+
```npmrc
451+
shamefully-hoist=true
452+
```
453+
<Alert level="warning">
454+
**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.
455+
</Alert>
455456
456457
457-
</Expandable>
458+
</Expandable>
459+
</PlatformSection>
460+
461+
<PlatformSection supported={['javascript.nuxt']}>
462+
<Expandable title="'import-in-the-middle' error during startup">
463+
After adding `sentry.server.config.ts` and building the project, you might get an error like this:
464+
`Failed to register ESM hook import-in-the-middle/hook.mjs`. You can add an override (npm/pnpm) or a resolution (yarn)
465+
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).
466+
467+
468+
Nitro updated `@vercel/nft` in Nitro version `2.10.0`, so you might not get this error anymore, and you don't need to
469+
add this override/resolution.
470+
471+
```json {tabTitle:npm} {filename:package.json}
472+
"overrides": {
473+
"@vercel/nft": "^0.27.4"
474+
}
475+
```
476+
477+
```json {tabTitle:yarn} {filename:package.json}
478+
"resolutions": {
479+
"@vercel/nft": "^0.27.4"
480+
}
481+
```
482+
483+
```json {tabTitle:pnpm} {filename:package.json}
484+
"pnpm": {
485+
"overrides": {
486+
"@vercel/nft": "^0.27.4"
487+
}
488+
}
489+
```
490+
491+
</Expandable>
492+
493+
<Expandable permalink title="pnpm: Resolving 'import-in-the-middle' external package errors">
494+
495+
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.
496+
As pnpm implements a strict dependency isolation, this import might cause problems.
497+
Per default, `shamefully-hoist` is `false` ([pnpm docs here](https://pnpm.io/next/npmrc#shamefully-hoist)) and this prevents accessing non-declared dependencies.
498+
You probably don't want to change this setting, so you have to explicitly add the dependency `import-in-the-middle`:
499+
500+
```bash
501+
pnpm add import-in-the-middle
502+
```
503+
</Expandable>
504+
</PlatformSection>
458505
459506
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‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
title: Manual Setup
3+
sidebar_order: 1
4+
description: "Learn how to set up the SDK manually."
5+
---
6+
7+
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.
8+
9+
## Compatibility
10+
11+
The minimum supported Nuxt version is `3.7.0`.
12+
13+
## Install
14+
15+
```bash {tabTitle:npm}
16+
npm install @sentry/nuxt --save
17+
```
18+
19+
```bash {tabTitle:yarn}
20+
yarn add @sentry/nuxt
21+
```
22+
23+
```bash {tabTitle:pnpm}
24+
pnpm add @sentry/nuxt
25+
```
26+
27+
## Configure
28+
29+
Configuration should happen as early as possible in your application's lifecycle.
30+
31+
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:
32+
33+
- Client-Side: `sentry.client.config.ts` in the root containing `Sentry.init`
34+
- Server-Side: `sentry.server.config.ts` in the root containing `Sentry.init`
35+
36+
In these files, you can specify the full range of <PlatformLink to="/configuration/options">Sentry SDK options</PlatformLink>.
37+
38+
39+
### Nuxt Module Setup
40+
41+
Add the Sentry Nuxt Module to your `nuxt.config.ts` file:
42+
43+
```javascript {filename:nuxt.config.ts}
44+
export default defineNuxtConfig({
45+
modules: ["@sentry/nuxt/module"]
46+
});
47+
```
48+
49+
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.
50+
51+
### Client-side Setup
52+
53+
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:
54+
55+
```javascript {filename:sentry.client.config.ts}
56+
import * as Sentry from '@sentry/nuxt';
57+
58+
Sentry.init({
59+
// If set up, you can use your runtime config here
60+
// dsn: useRuntimeConfig().public.sentry.dsn,
61+
dsn: "___PUBLIC_DSN___",
62+
63+
// We recommend adjusting this value in production, or using tracesSampler
64+
// for finer control
65+
tracesSampleRate: 1.0
66+
});
67+
```
68+
69+
### Server-side Setup
70+
71+
Add a `sentry.server.config.ts` file to the root of your project:
72+
73+
```javascript {filename:sentry.server.config.ts}
74+
import * as Sentry from '@sentry/nuxt';
75+
76+
Sentry.init({
77+
dsn: "___PUBLIC_DSN___",
78+
79+
// We recommend adjusting this value in production, or using tracesSampler
80+
// for finer control
81+
tracesSampleRate: 1.0
82+
});
83+
```
84+
85+
The Nuxt `useRuntimeConfig()` does not work in the Sentry server config due to technical reasons (the config file has to
86+
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
87+
88+
```bash {tabTitle: node}
89+
node --env-file=.env .output/server/index.mjs
90+
```
91+
92+
or use the `dotenv` package:
93+
94+
```javascript {tabTitle: Server Config} {filename:sentry.server.config.ts} {1,3}
95+
import dotenv from 'dotenv';
96+
97+
dotenv.config();
98+
99+
// ... rest of the file
100+
```
101+
102+
<Alert level="warning">
103+
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)
104+
</Alert>
105+
106+
#### Troubleshoot Errors during Server Startup
107+
108+
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>.
109+
110+
## Source Maps Upload
111+
112+
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.
113+
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.
114+
115+
To upload source maps, specify your Sentry auth token as well as your org and project slugs. Set them in the `sourceMapsUploadOptions` option
116+
inside the `sentry` options of your `nuxt.config.ts`.
117+
118+
<Alert level="info">
119+
The module options inside `sentry` are only affecting the **build-time** of the SDK.
120+
</Alert>
121+
122+
<OrgAuthTokenNote />
123+
124+
```javascript {filename:nuxt.config.ts} {3-9}
125+
export default defineNuxtConfig({
126+
modules: ["@sentry/nuxt/module"],
127+
sentry: {
128+
sourceMapsUploadOptions: {
129+
org: "___ORG_SLUG___",
130+
project: "___PROJECT_SLUG___",
131+
authToken: "___ORG_AUTH_TOKEN___"
132+
}
133+
}
134+
});
135+
```
136+
137+
To upload source maps, the Sentry Nuxt Module will automatically enable source map generation in your project if it is not already enabled.
138+
However, you need to explicitly enable source map generation on the client-side. To do this, add the following code to your Nuxt configuration:
139+
140+
```javascript {filename:nuxt.config.ts} {2}
141+
export default defineNuxtConfig({
142+
sourcemap: { client: true }
143+
});
144+
```
145+
146+
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.
147+
148+
## Verify
149+
150+
This snippet includes an intentional error, so you can test that everything is working as soon as you set it up.
151+
152+
<PlatformContent includePath="getting-started-verify" />

0 commit comments

Comments
 (0)