feat(nuxt): Improve Nuxt server-side setup docs #12102
Open
+88
−74
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
1 Skipped Deployment
|
Bundle ReportChanges will increase total bundle size by 143 bytes (0.0%) ⬆️. This is within the configured threshold ✅ Detailed changes
|
mydea
reviewed
Dec 12, 2024
| @@ -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. | |||
There was a problem hiding this comment.
Suggested change
| 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 import graph of your application is resolved by Node. This is necessary for instrumentation of ESM modules to be possible. |
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.
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"
mydea
reviewed
Dec 12, 2024
|
|
||
| ## 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.
Suggested change
| - 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. | |
| - 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, e.g. at build time. |
There was a problem hiding this comment.
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.
@s1gr1d is right :) we avoid latin abbreviations
mydea
reviewed
Dec 12, 2024
Comment on lines
16
to
17
| - **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.
Suggested change
| - **Netlify** only allows scoped environment variables on its paid plans at this time | |
| - **Vercel** doesn't currently provide an option for scoping environment variables | |
| - On **Netlify**, it is as of now not possible to configure `--import` properly. | |
| - On **Vercel**, it is as of now not possible to configure `--import` properly. |
should we just write it like this? 🤔 As the unknown path is also an issue there, in addition to the scopes variables stuff?
mydea
reviewed
Dec 12, 2024
| - **Netlify** only allows scoped environment variables on its paid plans at this time | ||
| - **Vercel** doesn't currently provide an option for scoping environment variables | ||
|
|
||
| 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.
Suggested change
| Check out the guide for using <PlatformLink to="/install/top-level-import/">a top-level import</PlatformLink> instead. | |
| Check out the guide for using <PlatformLink to="/install/limited-server-tracing/">limited server tracing</PlatformLink> instead. |
mydea
reviewed
Dec 12, 2024
| 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.
Suggested change
| This installation method comes with restrictions when using more recent versions of Nuxt/Nitro. | |
| This installation method does not work with more recent versions of Nuxt/Nitro. |
is this not more correct? 😅
There was a problem hiding this comment.
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.
mydea
reviewed
Dec 12, 2024
| }, | ||
| }) | ||
| ``` | ||
| 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.
Suggested change
| 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> | |
| We recommend the guide for installing the SDK with the <PlatformLink to="/install/cli-import">CLI flag `--import`</PlatformLink> or a <PlatformLink to="/install/limited-server-tracing/">limited server tracing</PlatformLink> |
mydea
reviewed
Dec 12, 2024
| @@ -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.
Suggested change
| 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>. | |
| 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/limited-server-tracing/">limited-server-tracing</PlatformLink>. |
mydea
reviewed
Dec 12, 2024
| @@ -1,20 +1,21 @@ | |||
| --- | |||
| title: Top-level import | |||
| title: Limited Server Tracing | |||
There was a problem hiding this comment.
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.
It was online for quite some time so maybe not a bad idea
mydea
reviewed
Dec 12, 2024
| --- | ||
|
|
||
| ## Understanding Top-level `import` | ||
| ## Understanding Limited Server Tracing | ||
|
|
||
| Sentry needs to be initialized before the application starts. |
There was a problem hiding this comment.
Suggested change
| Sentry needs to be initialized before the application starts. | |
| Sentry needs to be initialized before the import graph is resolved by Node. |
mydea
reviewed
Dec 12, 2024
|
|
||
| ``` | ||
|
|
||
| <Alert level="warning"> |
There was a problem hiding this comment.
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.
I made part of it an alert. So the notice about dev mode and the troubleshooting link are in the alert.
lizokm
approved these changes
Dec 24, 2024
| - You're not able to add Node CLI flags or environment variables that are scoped to the function runtime | ||
| - **Netlify** only allows scoped environment variables on its paid plans at this time | ||
| - **Vercel** doesn't currently provide an option for scoping environment variables | ||
| - 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.
Suggested change
| - 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. | |
| - You're unable to add Node CLI flags or environment variables scoped to the function runtime, meaning these variables aren't applied in other scopes, such as build time. |
|
|
||
| ## 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.
@s1gr1d is right :) we avoid latin abbreviations
Comment on lines
+16
to
+18
| - You don't know the path to the Nuxt server folder in the build output | ||
| - On **Netlify**, it is as of now not possible to configure `--import` properly. | ||
| - On **Vercel**, it is as of now not possible to configure `--import` properly. |
There was a problem hiding this comment.
Suggested change
| - You don't know the path to the Nuxt server folder in the build output | |
| - On **Netlify**, it is as of now not possible to configure `--import` properly. | |
| - On **Vercel**, it is as of now not possible to configure `--import` properly. | |
| - You don't know the path to the Nuxt server folder in the build output | |
| - At this time, it isn't possible to properly configure `--import` in **Netlify**. | |
| - At this time, it isn't possible to properly configure `--import` in **Vercel**. |
| 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 does not work with more recent versions of Nuxt/Nitro. |
There was a problem hiding this comment.
Suggested change
| This installation method does not work with more recent versions of Nuxt/Nitro. | |
| This installation method doesn't work with more recent versions of Nuxt/Nitro. |
| This early initialization is required to set up the SDK's instrumentation of various libraries correctly. | ||
|
|
||
| ## Initializing Sentry with Dynamic `import()` | ||
| We recommend the guide for installing the SDK with the <PlatformLink to="/install/cli-import">CLI flag `--import`</PlatformLink> or <PlatformLink to="/install/limited-server-tracing">limited server tracing</PlatformLink> |
There was a problem hiding this comment.
Suggested change
| We recommend the guide for installing the SDK with the <PlatformLink to="/install/cli-import">CLI flag `--import`</PlatformLink> or <PlatformLink to="/install/limited-server-tracing">limited server tracing</PlatformLink> | |
| We recommend reading the guide for installing the SDK with the <PlatformLink to="/install/cli-import">CLI flag `--import`</PlatformLink> or <PlatformLink to="/install/limited-server-tracing">limited server tracing</PlatformLink> |
| If the default way of adding an <PlatformLink to="/install/cli-import">`--import` CLI flag</PlatformLink> flag does not work for you, | ||
| 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.
Suggested change
| set up the SDK for adding a top-level `import`. | |
| enable the SDK to add a top-level `import`. |
| 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`. | ||
|
|
||
| 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.
Suggested change
| The automatically added top-level `import` will import the Sentry server-side config at the top of the Nuxt server entry file. | |
| The automatically added top-level `import` will then import the Sentry server-side config to the top of the Nuxt server entry file. |
| 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.
Suggested change
| The SDK then automatically imports this file at the top of the Nitro server entry in the build output. | |
| The SDK will then automatically import this file to the top of the Nitro server entry in the build output. |
| ``` | ||
|
|
||
| <Alert level="warning"> | ||
| Sentry server-side monitoring **does not work in development mode!** |
There was a problem hiding this comment.
Suggested change
| Sentry server-side monitoring **does not work in development mode!** | |
| Sentry server-side monitoring **doesn't work in development mode!** |
Comment on lines
+26
to
+28
| 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.
Suggested change
| 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> | |
| If 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> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
DESCRIBE YOUR PR
Further improve the Nuxt server-side setup docs after feedback.
IS YOUR CHANGE URGENT?
Help us prioritize incoming PRs by letting us know when the change needs to go live.
SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes: