Skip to content

Commit 305f0fa

Browse files
s1gr1ds1gr1d
committed
docs(nuxt): Add Nuxt wizard instructions
1 parent b2e2dc0 commit 305f0fa

File tree

6 files changed

+107
-168
lines changed

6 files changed

+107
-168
lines changed

‎platform-includes/getting-started-config/javascript.nuxt.mdx‎

Lines changed: 2 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,118 +1,2 @@
1-
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:
2-
3-
- Client-Side: `sentry.client.config.ts` in the root containing `Sentry.init`
4-
- Server-Side: `sentry.server.config.ts` in the root containing `Sentry.init`
5-
6-
In these files, you can specify the full range of <PlatformLink to="/configuration/options">Sentry SDK options</PlatformLink>.
7-
8-
9-
### Nuxt Module Setup
10-
11-
Add the Sentry Nuxt Module to your `nuxt.config.ts` file:
12-
13-
```javascript {filename:nuxt.config.ts}
14-
export default defineNuxtConfig({
15-
modules: ["@sentry/nuxt/module"]
16-
});
17-
```
18-
19-
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.
20-
21-
### Client-side Setup
22-
23-
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:
24-
25-
```javascript {filename:sentry.client.config.ts}
26-
import * as Sentry from '@sentry/nuxt';
27-
28-
Sentry.init({
29-
// If set up, you can use your runtime config here
30-
// dsn: useRuntimeConfig().public.sentry.dsn,
31-
dsn: "___PUBLIC_DSN___",
32-
33-
// We recommend adjusting this value in production, or using tracesSampler
34-
// for finer control
35-
tracesSampleRate: 1.0
36-
});
37-
```
38-
39-
### Server-side Setup
40-
41-
1. Add a `sentry.server.config.ts` file to the root of your project:
42-
43-
```javascript {filename:sentry.server.config.ts}
44-
import * as Sentry from '@sentry/nuxt';
45-
46-
Sentry.init({
47-
dsn: "___PUBLIC_DSN___",
48-
49-
// We recommend adjusting this value in production, or using tracesSampler
50-
// for finer control
51-
tracesSampleRate: 1.0
52-
});
53-
```
54-
55-
The Nuxt `useRuntimeConfig()` does not work in the Sentry server config due to technical reasons (the config file has to
56-
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
57-
58-
```bash {tabTitle: node}
59-
node --env-file=.env .output/server/index.mjs
60-
```
61-
62-
or use the `dotenv` package:
63-
64-
```javascript {tabTitle: Server Config} {filename:sentry.server.config.ts} {1,3}
65-
import dotenv from 'dotenv';
66-
67-
dotenv.config();
68-
69-
// ... rest of the file
70-
```
71-
72-
<Alert level="warning">
73-
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)
74-
</Alert>
75-
76-
#### Troubleshoot Errors during Server Startup
77-
78-
After adding `sentry.server.config.ts` and building the project, you might get an error like this:
79-
`Failed to register ESM hook import-in-the-middle/hook.mjs`. You can add an override (npm/pnpm) or a resolution (yarn)
80-
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).
81-
82-
83-
Nitro updated `@vercel/nft` in Nitro version `2.10.0`, so you might not get this error anymore, and you don't need to
84-
add this override/resolution.
85-
86-
```json {tabTitle:npm} {filename:package.json}
87-
"overrides": {
88-
"@vercel/nft": "^0.27.4"
89-
}
90-
```
91-
92-
```json {tabTitle:yarn} {filename:package.json}
93-
"resolutions": {
94-
"@vercel/nft": "^0.27.4"
95-
}
96-
```
97-
98-
```json {tabTitle:pnpm} {filename:package.json}
99-
"pnpm": {
100-
"overrides": {
101-
"@vercel/nft": "^0.27.4"
102-
}
103-
}
104-
```
105-
106-
**Pnpm and Import-In-The-Middle**
107-
108-
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.
109-
As pnpm implements a strict dependency isolation, this import might cause problems.
110-
Per default, `shamefully-hoist` is `false` ([pnpm docs here](https://pnpm.io/next/npmrc#shamefully-hoist)) and this prevents accessing non-declared dependencies.
111-
You probably don't want to change this setting, so you have to explicitly add the dependency `import-in-the-middle`:
112-
113-
```json {tabTitle:pnpm} {filename:package.json}
114-
// only when using pnpm
115-
"dependencies": {
116-
"import-in-the-middle": "^1.11.2"
117-
}
118-
```
1+
To complete your configuration, add <PlatformLink to="/configuration/options/">options</PlatformLink> to your `Sentry.init()` calls.
2+
Here, you'll also be able to set context data, which includes data about the <PlatformLink to="/enriching-events/identify-user/">user</PlatformLink>, <PlatformLink to="/enriching-events/tags/">tags</PlatformLink>, or even <PlatformLink to="/enriching-events/context/">arbitrary data</PlatformLink>, all of which will be added to every event sent to Sentry.

‎platform-includes/getting-started-install/javascript.nuxt.mdx‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,21 @@
1-
```bash {tabTitle:npm}
2-
npm install @sentry/nuxt --save
3-
```
1+
We recommend installing the SDK by running our installation wizard in the root directory of your project:
42

5-
```bash {tabTitle:yarn}
6-
yarn add @sentry/nuxt
3+
```bash
4+
npx @sentry/wizard@latest -i nuxt
75
```
86

9-
```bash {tabTitle:pnpm}
10-
pnpm add @sentry/nuxt
11-
```
7+
The wizard will prompt you to log in to Sentry. It will then automatically do the following steps for you:
8+
9+
- create or update Nuxt files with the default Sentry configuration:
10+
- `sentry.(client|server).config.ts` to initialize the SDK
11+
- `nuxt.config.ts` to add build options to add source maps upload and auto-instrumentation via Vite plugins.
12+
- create a `.env.sentry-build-plugin` file with an auth token to upload source maps (this file is automatically added to `.gitignore`)
13+
- add an example page to your frontend app and your server to verify your Sentry setup
14+
15+
After the wizard setup is completed, the SDK will automatically capture unhandled errors, and monitor performance.
16+
17+
You can also <PlatformLink to="/usage/">manually capture errors</PlatformLink>.
18+
19+
<Note>
20+
If the setup through the wizard doesn't work for you, you can also <PlatformLink to="/manual-setup/">set up the SDK manually</PlatformLink>.
21+
</Note>

‎platform-includes/getting-started-next-steps/javascript.nuxt.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,7 @@
11
## Next Steps
22

33
- Track your Vue Components or your Pinia store by [adding support for client features](/platforms/javascript/guides/nuxt/features/)
4+
- In case you experience any issues during setup or startup, check out <PlatformLink to="/troubleshooting">Troubleshooting</PlatformLink>
5+
6+
7+
or read through the different <PlatformLink to="/install">installation methods</PlatformLink>.

‎platform-includes/getting-started-primer/javascript.nuxt.mdx‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,41 @@
22
This SDK is currently in **beta**. Beta features are still in progress and may have bugs. Please reach out on
33
[GitHub](https://github.com/getsentry/sentry-javascript/issues/new/choose) if you have any feedback or concerns.
44
</Alert>
5+
6+
7+
Sentry's Nuxt SDK enables automatic reporting of errors and performance data.
8+
9+
## Compatibility
10+
11+
The minimum supported Nuxt version is `3.7.0`.
12+
13+
<Note>
14+
We are currently investigating an issue where the server-side is not correctly initialized with a recent update of Nitro (the server-side toolkit in Nuxt).
15+
16+
We are working on figuring this out ([see issue here](https://github.com/getsentry/sentry-javascript/issues/14514)). For the time being, you can add the following overrides to your application:
17+
18+
<br/>
19+
20+
```json {tabTitle:npm} {filename:package.json}
21+
"overrides": {
22+
"nitropack": "2.9.7"
23+
"@vercel/nft": "^0.27.4"
24+
}
25+
```
26+
27+
```json {tabTitle:yarn} {filename:package.json}
28+
"resolutions": {
29+
"nitropack": "2.9.7"
30+
"@vercel/nft": "^0.27.4"
31+
}
32+
```
33+
34+
```json {tabTitle:pnpm} {filename:package.json}
35+
"pnpm": {
36+
"overrides": {
37+
"nitropack": "2.9.7"
38+
"@vercel/nft": "^0.27.4"
39+
}
40+
}
41+
```
42+
</Note>

‎platform-includes/getting-started-sourcemaps/javascript.nuxt.mdx‎

Lines changed: 0 additions & 37 deletions
This file was deleted.

‎platform-includes/getting-started-verify/javascript.nuxt.mdx‎

Lines changed: 45 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,54 @@
1-
```html {tabTitle:Vue} {filename:ErrorButton.vue}
1+
On the client-side:
2+
3+
```html {tabTitle:Vue} {filename:pages/example-error.vue}
24
<script setup>
3-
const triggerError = () => {
4-
throw new Error("Nuxt Button Error");
5-
};
5+
import * as Sentry from '@sentry/nuxt';
6+
import { useFetch} from '#imports'
7+
8+
function triggerClientError() {
9+
throw new Error("Nuxt Button Error");
10+
};
11+
12+
function getSentryData() {
13+
Sentry.startSpan(
14+
{
15+
name: 'Example Frontend Span',
16+
op: 'test'
17+
},
18+
async () => {
19+
await useFetch('/sentry-example-api');
20+
}
21+
)
22+
}
623
</script>
724

825
<template>
9-
<button id="errorBtn" @click="triggerError">Trigger Error</button>
26+
<button id="errorBtn" @click="triggerClientError">
27+
Throw Client Error
28+
</button>
29+
<button type="button" @click="getSentryData">
30+
Throw Server Error
31+
</button>
1032
</template>
1133
```
1234

35+
On the server-side:
36+
37+
```js {tabTitle:Nitro} {filename:server/sentry-example-api.ts}
38+
import { defineEventHandler } from '#imports';
39+
40+
export default defineEventHandler(event => {
41+
throw new Error("Sentry Example API Route Error");
42+
});
43+
44+
```
1345

46+
<Alert level="warning">
47+
Keep in mind, that the server-side monitoring **does not work in development mode!**
1448

49+
If you want to test server-side monitoring locally, build your project and run:
50+
```
51+
# Start your app after building your project with `nuxi build`
52+
node .output/server/index.mjs
53+
```
54+
</Alert>

0 commit comments

Comments
 (0)