feat(nuxt): Improve Nuxt server-side setup docs #12102
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
2 Skipped Deployments
|
Bundle ReportChanges will increase total bundle size by 143 bytes (0.0%) ⬆️. This is within the configured threshold ✅ Detailed changes
|
| @@ -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.
| 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"
There was a problem hiding this comment.
After Lizas review, I took a look at this again and I think this is true for the dynamic import (as it creates a new import graph). But for --import it's actually correct, that it loads before the application starts.
However, I will update it in the dynamic import page, as I wrote the same sentence there.
From the Node docs:
- "The hooks can be registered before the application code is run by using the
--import." here - "Preload the specified module at startup." here
I'll change it to this:
The
--importCLI flag in Node is the default way in ESM to preload a specified module at startup.
Setting this CLI flag is crucial for ensuring proper server-side initialization, as Sentry needs to be initialized before the application runs.
This will register Sentry's loader hook and therefore enable proper instrumentation of ESM modules.
| - **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.
| - **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?
docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx
Outdated
Show resolved
Hide resolved
| }, | ||
| }) | ||
| ``` | ||
| 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.
| 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> |
docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx
Outdated
Show resolved
Hide resolved
| @@ -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
| --- | ||
|
|
||
| ## Understanding Top-level `import` | ||
| ## Understanding Limited Server Tracing | ||
|
|
||
| Sentry needs to be initialized before the application starts. |
There was a problem hiding this comment.
| Sentry needs to be initialized before the application starts. | |
| Sentry needs to be initialized before the import graph is resolved by Node. |
|
|
||
| ``` | ||
|
|
||
| <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.
docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx
Outdated
Show resolved
Hide resolved
docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx
Outdated
Show resolved
Hide resolved
| 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.
| 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.
| 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.
| 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. |
s1gr1d
force-pushed
the
sig/nuxt-setup-improve
branch
from
75d0725 to
3b3400c
Compare
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: