-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat(nuxt): Improve Nuxt server-side setup docs #12102
base: master
Are you sure you want to change the base?
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
@@ -7,17 +7,17 @@ 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. | ||||||||||
Setting this flag is crucial for ensuring proper server-side initialization, as Sentry needs to be initialized before the rest of the application runs. | ||||||||||
|
||||||||||
## 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 | ||||||||||
- You're not able to add Node CLI flags or environment variables scoped to the function runtime, meaning these variables are not applied in other scopes, such as build time. | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think we shouldn't use abbreviations like e.g. but let's see what Liza has to say :) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @s1gr1d is right :) we avoid latin abbreviations There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
- You don't know the path to the Nuxt server folder in the build output | ||||||||||
- **Netlify** only allows scoped environment variables on its paid plans at this time | ||||||||||
- **Vercel** doesn't currently provide an option for scoping environment variables | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
should we just write it like this? 🤔 As the unknown path is also an issue there, in addition to the scopes variables stuff? |
||||||||||
|
||||||||||
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/top-level-import/">a top-level import</PlatformLink> instead. | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
|
||||||||||
## Initializing Sentry with `--import` | ||||||||||
|
||||||||||
|
Original file line number | Diff line number | Diff line change | ||||||
---|---|---|---|---|---|---|---|---|
|
@@ -6,37 +6,17 @@ 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 comes with restrictions when using more recent versions of Nuxt/Nitro. | ||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
is this not more correct? 😅 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It can work sometimes 😄 I had it working with newer versions, but only under certain conditions. But yeah, probably it's better to just say it's not working to be more precise. |
||||||||
|
||||||||
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. | ||||||||
|
||||||||
## 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' | ||||||||
}, | ||||||||
}) | ||||||||
``` | ||||||||
We recommend the guide for installing the SDK with the <PlatformLink to="/install/cli-import">CLI flag `--import`</PlatformLink> or a <PlatformLink to="/install/top-level-import/">top-level import</PlatformLink> | ||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||
</Alert> | ||||||||
|
||||||||
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: "..." | ||||||||
}); | ||||||||
The `import()` expression, or dynamic import, enables flexible, conditional module loading in ESM. | ||||||||
For the Sentry Nuxt SDK, it provides an approach to initialize server-side Sentry configuration before application startup. | ||||||||
Comment on lines
+15
to
+16
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||
|
||||||||
import('./chunks/nitro/nitro.mjs').then(function (n) { return n.r; }); | ||||||||
``` | ||||||||
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. | ||||||||
Comment on lines
+18
to
+19
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||
|
||||||||
## Scenarios where `import()` doesn't work | ||||||||
|
||||||||
|
@@ -67,7 +47,34 @@ 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 a <PlatformLink to="/install/top-level-import/">top-level import</PlatformLink>. | ||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||
|
||||||||
|
||||||||
## 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 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. | ||||||||
Comment on lines
+64
to
+65
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||
|
||||||||
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 | ||||||||
|
||||||||
|
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -1,20 +1,21 @@ | ||||||
--- | ||||||
title: Top-level import | ||||||
title: Limited Server Tracing | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Not sure, do we need to add a redirect for this renamed page? 🤔 Not sure how many links to the /top-level-import path are reasonably out there...? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It was online for quite some time so maybe not a bad idea |
||||||
sidebar_order: 2 | ||||||
description: "Learn about how the Nuxt SDK adds a top-level import to the build output." | ||||||
description: "Learn about how the Nuxt SDK can be set up with limited server tracing by adding a top-level import to the build output." | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
--- | ||||||
|
||||||
## Understanding Top-level `import` | ||||||
## Understanding Limited Server Tracing | ||||||
|
||||||
Sentry needs to be initialized before the application starts. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
If the default way of adding an <PlatformLink to="/install/cli-import">`--import` CLI flag</PlatformLink> flag does not work for you, | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
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. | ||||||
set up the SDK for adding a top-level `import`. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
The automatically added top-level `import` will import the Sentry server-side config at the top of the Nuxt server entry file. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
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 then automatically imports this file at the top of the Nitro server entry in the build output. | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
Original file line number | Diff line number | Diff line change | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
@@ -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"); | ||||||||||||||
}); | ||||||||||||||
|
||||||||||||||
``` | ||||||||||||||
|
||||||||||||||
<Alert level="warning"> | ||||||||||||||
Sentry server-side monitoring **does not work in development mode!** | ||||||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Not 100% sure, but do we need to make this an alert? What about instead, just making this regular text? This is part of the server-side verify step basically, isn't it? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I made part of it an alert. So the notice about dev mode and the troubleshooting link are in the alert. |
||||||||||||||
|
||||||||||||||
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 | ||||||||||||||
``` | ||||||||||||||
|
||||||||||||||
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> | ||||||||||||||
|
||||||||||||||
Comment on lines
+26
to
+28
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||||||
### 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> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is not fully correct, or possibly misleading, because import at the top would also be "before the rest of the application runs". Actually, the problem is that Sentry needs to be initialized "before the import graph is resolved" 🤔 Which is why this has to happen in
--import
. Not sure how easy that is to understand though 😅There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
True, I changed it a bit: "Setting this flag is crucial for ensuring proper server-side initialization, as Sentry needs to be initialized before Node.js resolves the entire import graph of your application. This is necessary for enabling proper instrumentation of ESM module"