From 433600dbf84fde70290b4cf806013678a8c38b09 Mon Sep 17 00:00:00 2001 From: s1gr1d Date: Wed, 27 Nov 2024 23:23:02 +0100 Subject: [PATCH 1/4] docs(nuxt): Add installation methods --- .../guides/nuxt/install/cli-import.mdx | 75 +++++++++++++++++++ .../guides/nuxt/install/dynamic-import.mdx | 7 ++ .../javascript/guides/nuxt/install/index.mdx | 10 +++ 3 files changed, 92 insertions(+) create mode 100644 docs/platforms/javascript/guides/nuxt/install/cli-import.mdx create mode 100644 docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx create mode 100644 docs/platforms/javascript/guides/nuxt/install/index.mdx diff --git a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx new file mode 100644 index 0000000000000..5fa887ea09e12 --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx @@ -0,0 +1,75 @@ +--- +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.js allows you to preload modules before your 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 + + + +## 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`: + +```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 the CLI 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' +``` diff --git a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx new file mode 100644 index 0000000000000..10ba2b31ca433 --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx @@ -0,0 +1,7 @@ +--- +title: Dynamic Import (default) +sidebar_order: 1 +description: "Learn about how the Nuxt SDK leverages dynamic input() in the build output." +--- + +TODO diff --git a/docs/platforms/javascript/guides/nuxt/install/index.mdx b/docs/platforms/javascript/guides/nuxt/install/index.mdx new file mode 100644 index 0000000000000..3017e65604afd --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/install/index.mdx @@ -0,0 +1,10 @@ +--- +title: Installation Methods +sidebar_order: 1.5 +description: "Review our alternate installation methods." +--- + + + + +TODO: Nuxt is using ES Modules on the server-side so... From caa2c808b6ef53b36cb6b93964c275703d74e3e3 Mon Sep 17 00:00:00 2001 From: s1gr1d Date: Thu, 28 Nov 2024 16:14:40 +0100 Subject: [PATCH 2/4] update installation pages --- .../guides/nuxt/install/cli-import.mdx | 9 ++- .../guides/nuxt/install/dynamic-import.mdx | 74 ++++++++++++++++++- .../javascript/guides/nuxt/install/index.mdx | 7 +- .../javascript/guides/nuxt/manual-setup.mdx | 3 +- 4 files changed, 88 insertions(+), 5 deletions(-) diff --git a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx index 5fa887ea09e12..5e8e4cb8518b6 100644 --- a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx @@ -6,12 +6,17 @@ 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.js allows you to preload modules before your application starts. +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 +- 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 dynamic import as this might be a better choice for you. ## Initializing Sentry with `--import` @@ -58,7 +63,7 @@ To make things easier, add a script in the `package.json`: } ``` -### 3. Adding the CLI flag in production +### 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. diff --git a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx index 10ba2b31ca433..736cfdc40379d 100644 --- a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx @@ -4,4 +4,76 @@ sidebar_order: 1 description: "Learn about how the Nuxt SDK leverages dynamic input() in the build output." --- -TODO +## 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. + +## Scenarios where `import()` does not work + +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 CLI flag `--import` 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'] + }, +}); +``` + + + + diff --git a/docs/platforms/javascript/guides/nuxt/install/index.mdx b/docs/platforms/javascript/guides/nuxt/install/index.mdx index 3017e65604afd..0f786f91e9f5d 100644 --- a/docs/platforms/javascript/guides/nuxt/install/index.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/index.mdx @@ -6,5 +6,10 @@ description: "Review our alternate installation methods." +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. -TODO: Nuxt is using ES Modules on the server-side so... +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 diff --git a/docs/platforms/javascript/guides/nuxt/manual-setup.mdx b/docs/platforms/javascript/guides/nuxt/manual-setup.mdx index 22dcf2dc7095a..edad433089fa8 100644 --- a/docs/platforms/javascript/guides/nuxt/manual-setup.mdx +++ b/docs/platforms/javascript/guides/nuxt/manual-setup.mdx @@ -105,7 +105,8 @@ dotenv.config(); #### Troubleshoot Errors during Server Startup -In case you are experiencing problems after adding `sentry.server.config.ts` and building the project, you can check out Troubleshooting. +In case you are experiencing problems after adding `sentry.server.config.ts` and building the project, you can check out Troubleshooting +or read through the different installation methods. ## Source Maps Upload From e32026d80b25f6e311126ef4f62a02d6441ade16 Mon Sep 17 00:00:00 2001 From: s1gr1d Date: Fri, 29 Nov 2024 09:56:07 +0100 Subject: [PATCH 3/4] review suggestions --- .../guides/nuxt/install/cli-import.mdx | 10 ++--- .../guides/nuxt/install/dynamic-import.mdx | 39 ++++++++++--------- .../javascript/guides/nuxt/install/index.mdx | 5 +-- 3 files changed, 28 insertions(+), 26 deletions(-) diff --git a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx index 5e8e4cb8518b6..5c5739455a805 100644 --- a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx @@ -7,16 +7,17 @@ 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. +If you cannot use the SDK's default dynamic import behaviour, 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 are 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 that are scoped to the function runtime - 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 dynamic import as this might be a better choice for you. +Check out the guide for using dynamic import instead. ## Initializing Sentry with `--import` @@ -24,8 +25,7 @@ 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`: +First, disable the dynamic import by setting `dynamicImportForServerEntry` to `false`: ```javascript {filename: nuxt.config.ts} {5} export default defineNuxtConfig({ diff --git a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx index 736cfdc40379d..3a4c88db8daf3 100644 --- a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx @@ -8,8 +8,25 @@ description: "Learn about how the Nuxt SDK leverages dynamic input() in the buil 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. +This early initialization is required to set up the SDK's instrumentation of various libraries correctly. -## Scenarios where `import()` does not work +## 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; }); +``` + +## Scenarios where `import()` doesn't work 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: @@ -38,22 +55,6 @@ We are working on figuring this out ([see issue here](https://github.com/getsent You can also check out the guide for using the CLI flag `--import` 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. @@ -62,7 +63,7 @@ By default, Sentry re-exports functions named `handler`, `server`, and `default` In case your serverless function has another, custom name you can override this with `entrypointWrappedFunctions`: -```javascript {filename: nuxt.config.ts} {6} +```javascript {filename: nuxt.config.ts} {7} export default defineNuxtConfig({ modules: ["@sentry/nuxt/module"], @@ -77,3 +78,5 @@ export default defineNuxtConfig({ + + diff --git a/docs/platforms/javascript/guides/nuxt/install/index.mdx b/docs/platforms/javascript/guides/nuxt/install/index.mdx index 0f786f91e9f5d..547a8bda34c89 100644 --- a/docs/platforms/javascript/guides/nuxt/install/index.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/index.mdx @@ -4,12 +4,11 @@ sidebar_order: 1.5 description: "Review our alternate installation methods." --- - + 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 + From 8e5bb911c797697713f068788c59c2f975b1da82 Mon Sep 17 00:00:00 2001 From: s1gr1d Date: Fri, 29 Nov 2024 09:57:11 +0100 Subject: [PATCH 4/4] remove lines --- .../javascript/guides/nuxt/install/dynamic-import.mdx | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx index 3a4c88db8daf3..9bc5e4c7a6735 100644 --- a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx @@ -74,9 +74,3 @@ export default defineNuxtConfig({ }, }); ``` - - - - - -