-
-
Notifications
You must be signed in to change notification settings - Fork 1.6k
docs(nuxt): Add installation methods #11983
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
Merged
Merged
Changes from 2 commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
80 changes: 80 additions & 0 deletions
80
docs/platforms/javascript/guides/nuxt/install/cli-import.mdx
This file contains hidden or 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,80 @@ | ||
| --- | ||
| title: --import CLI flag | ||
| sidebar_order: 2 | ||
| description: "Learn about using the node `--import` CLI flag." | ||
| --- | ||
|
|
||
| ## Understanding the `--import` CLI Flag | ||
|
|
||
| The [`--import` CLI flag](https://nodejs.org/api/cli.html#--importmodule) in Node allows you to preload modules before the application starts. | ||
| 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 are not able to add Node CLI flags or environment variables that are scoped to the function runtime | ||
s1gr1d marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
| - As of now, Netlify only supports adding scoped environment variables in the paid plan | ||
| - As of now, Vercel does not 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/dynamic-import/">dynamic import</PlatformLink> as this might be a better choice for you. | ||
s1gr1d marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ## Initializing Sentry with `--import` | ||
|
|
||
| To successfully use the `--import` flag, follow these steps: | ||
|
|
||
| ### 1. Disable Dynamic Import | ||
|
|
||
| First, you have to first disable the dynamic import. | ||
| This can be done by setting `dynamicImportForServerEntry` to `false`: | ||
s1gr1d marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| ```javascript {filename: nuxt.config.ts} {5} | ||
| export default defineNuxtConfig({ | ||
| modules: ["@sentry/nuxt/module"], | ||
|
|
||
| sentry: { | ||
| dynamicImportForServerEntry: false, | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
| By disabling the dynamic import, the SDK will add the Sentry server config to the build output (typically `.output/server/sentry.server.config.mjs`). | ||
|
|
||
| ### 2. Adding `--import` to `node` command | ||
|
|
||
| After building your Nuxt app with `nuxi build`, add the `--import` flag followed by the Sentry server config path to the `node` command. | ||
| With the default Nitro Node preset, this typically looks like this: | ||
|
|
||
| ```bash | ||
| node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs | ||
| ``` | ||
|
|
||
| Check the log at the very end of the console output after building the application. | ||
| This will print the node command with the server entry path for your application (`node .output/server/index.mjs` with the Node preset). | ||
| Make sure to update the paths accordingly, especially when using a different Nitro preset. | ||
|
|
||
| To make things easier, add a script in the `package.json`: | ||
|
|
||
| ```json {filename:package.json} | ||
| { | ||
| "scripts": { | ||
| "preview": "NODE_OPTIONS='--import .//server/sentry.server.config.mjs' nuxt preview", | ||
| "start": "node --import ./.output/server/sentry.server.config.mjs .output/server/index.mjs" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### 3. Adding `--import` flag in production | ||
|
|
||
| To be able to set up Sentry in production, the `--import` flag needs to be added wherever you run your application's production build output. | ||
| Consult your hosting provider's documentation for specific implementation details. | ||
| Most deployment platforms support this through two primary methods: | ||
|
|
||
| #### Option 1: Direct CLI Flag | ||
| ```bash | ||
| node --import .output/server/sentry.server.config.mjs your-server-entry.mjs | ||
| ``` | ||
|
|
||
| #### Option 2: Environment Variable | ||
| ```bash | ||
| NODE_OPTIONS='--import .output/server/sentry.server.config.mjs' | ||
| ``` | ||
79 changes: 79 additions & 0 deletions
79
docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx
s1gr1d marked this conversation as resolved.
Show resolved
Hide resolved
|
This file contains hidden or 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,79 @@ | ||
| --- | ||
| title: Dynamic Import (default) | ||
| sidebar_order: 1 | ||
| description: "Learn about how the Nuxt SDK leverages dynamic input() in the build output." | ||
| --- | ||
|
|
||
| ## 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. | ||
s1gr1d marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Scenarios where `import()` does not work | ||
s1gr1d marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
|
|
||
| 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). | ||
| We are working on figuring this out ([see issue here](https://github.com/getsentry/sentry-javascript/issues/14514)). As a temporary workaround, you can add the following overrides to your application: | ||
|
|
||
| ```json {tabTitle:npm} {filename:package.json} | ||
| "overrides": { | ||
| "nitropack": "2.9.7" | ||
| "@vercel/nft": "^0.27.4" | ||
| } | ||
| ``` | ||
| ```json {tabTitle:yarn} {filename:package.json} | ||
| "resolutions": { | ||
| "nitropack": "2.9.7" | ||
| "@vercel/nft": "^0.27.4" | ||
| } | ||
| ``` | ||
| ```json {tabTitle:pnpm} {filename:package.json} | ||
| "pnpm": { | ||
| "overrides": { | ||
| "nitropack": "2.9.7" | ||
| "@vercel/nft": "^0.27.4" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| You can also check out the guide for using the <PlatformLink to="/install/cli-import//">CLI flag `--import`</PlatformLink> as this might be a better choice for you. | ||
|
|
||
|
|
||
| ## Initializing Sentry with Dynamic `import()` | ||
|
|
||
| By default, the Sentry Nuxt SDK includes a Rollup plugin which wraps the server entry file with a dynamic `import()`. | ||
| With this, Sentry can be initialized before all other modules of the application. | ||
|
|
||
| The server entry file will look something like this: | ||
|
|
||
| ```javascript {filename:.output/server/index.mjs} | ||
| // Note: 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 | ||
|
|
||
| Sentry automatically detects serverless handler functions in the build output and re-exports them from the server entry file. | ||
|
|
||
| By default, Sentry re-exports functions named `handler`, `server`, and `default` exports. This will work in most cases and no other action is required. | ||
| In case your serverless function has another, custom name you can override this with `entrypointWrappedFunctions`: | ||
|
|
||
|
|
||
| ```javascript {filename: nuxt.config.ts} {6} | ||
| export default defineNuxtConfig({ | ||
| modules: ["@sentry/nuxt/module"], | ||
|
|
||
| sentry: { | ||
| // Customize detected function names | ||
| // Default value: ['default', 'handler', 'server'] | ||
| entrypointWrappedFunctions: ['customFunctionName'] | ||
| }, | ||
| }); | ||
| ``` | ||
|
|
||
|
|
||
|
|
||
|
|
||
This file contains hidden or 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| --- | ||
| title: Installation Methods | ||
| sidebar_order: 1.5 | ||
| description: "Review our alternate installation methods." | ||
| --- | ||
|
|
||
| <PageGrid /> | ||
|
|
||
| Nuxt uses ES Modules for server-side builds, which requires Sentry to register Node [customization hooks](https://nodejs.org/api/module.html#customization-hooks). | ||
| Those customization hooks need to be registered before the rest of the application. | ||
|
|
||
| To be able to run Sentry before the rest of the application and fully monitor the server-side, Sentry can be initialized using one of those two approaches: | ||
|
|
||
| - Dynamically import server code after initializing Sentry (default) | ||
| - Preload Sentry configuration with the Node `--import` CLI flag | ||
s1gr1d marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||
This file contains hidden or 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
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.
Uh oh!
There was an error while loading. Please reload this page.