From 878d13bc9a88550b7900d00a3bd547067e2b6455 Mon Sep 17 00:00:00 2001 From: s1gr1d Date: Fri, 6 Dec 2024 14:11:19 +0100 Subject: [PATCH 1/3] feat(nuxt): Use --import as the default installation method --- .../guides/nuxt/install/cli-import.mdx | 39 ++++++------------- .../guides/nuxt/install/dynamic-import.mdx | 29 ++++++++++---- .../guides/nuxt/install/top-level-import.mdx | 39 +++++++++++++++++++ .../javascript/guides/nuxt/manual-setup.mdx | 6 +++ 4 files changed, 79 insertions(+), 34 deletions(-) create mode 100644 docs/platforms/javascript/guides/nuxt/install/top-level-import.mdx diff --git a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx index 5c5739455a805..205aff0aeda13 100644 --- a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx @@ -1,45 +1,30 @@ --- -title: --import CLI flag -sidebar_order: 2 -description: "Learn about using the node `--import` CLI flag." +title: --import CLI flag (default) +sidebar_order: 1 +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. +The [`--import` CLI flag](https://nodejs.org/api/cli.html#--importmodule) in Node allows you to preload modules before the application starts. This is the default +way in ESM to load a module before the application starts. 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'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 +- 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 instead. +Check out the guide for using a top-level import or a dynamic import instead. ## Initializing Sentry with `--import` -To successfully use the `--import` flag, follow these steps: +By default, the SDK will add the Sentry server config to the build output (typically `.output/server/sentry.server.config.mjs`). -### 1. Disable Dynamic Import - -First, disable the dynamic import 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 +### 1. 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: @@ -57,13 +42,13 @@ 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", + "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 +### 2. 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 ef60ea8732a7c..0232e836ddc06 100644 --- a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx @@ -1,6 +1,6 @@ --- -title: Dynamic Import (default) -sidebar_order: 1 +title: Dynamic Import (experimental) +sidebar_order: 3 description: "Learn about how the Nuxt SDK leverages dynamic input() in the build output." --- @@ -8,17 +8,29 @@ 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. + +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()` -By default, the Sentry Nuxt SDK includes a Rollup plugin which wraps the server entry file with a 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 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 +// Note: The file may have some imports and code related to debug IDs Sentry.init({ dsn: "..." }); @@ -28,8 +40,11 @@ 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: +Depending on your setup and which version of Nitro is used, the server-side is sometimes not correctly initialized. +The build output **must not** include a regular `import` of the Nitro runtime (e.g. `import './chunks/nitro/nitro.mjs'`). +See the ([GitHub issue here](https://github.com/getsentry/sentry-javascript/issues/14514)) for more information. + +As a temporary workaround, you can add the following overrides to your application: ```json {tabTitle:npm} {filename:package.json} "overrides": { @@ -52,7 +67,7 @@ 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. +You can also check out the guide for using the CLI flag `--import` or a top-level import as this might be a better choice for you. ## Re-exporting serverless handler functions diff --git a/docs/platforms/javascript/guides/nuxt/install/top-level-import.mdx b/docs/platforms/javascript/guides/nuxt/install/top-level-import.mdx new file mode 100644 index 0000000000000..b6281ea22588a --- /dev/null +++ b/docs/platforms/javascript/guides/nuxt/install/top-level-import.mdx @@ -0,0 +1,39 @@ +--- +title: Top-level import +sidebar_order: 2 +description: "Learn about how the Nuxt SDK adds a top-level import to the build output." +--- + +## Understanding top-level `import` + +Sentry needs to be initialized before the application starts. +If the default way of adding an `--import` CLI flag 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 server entry file. +In this scenario, Sentry is not initialized before application startup, but as early as otherwise possible. + + + This installation method has a fundamental restriction: It only supports limited performance instrumentation. Only basic `http` instrumentation will work, and no DB or framework-specific instrumentation will be available. + + Because of this, we recommend using this only if the `--import` flag is not an option for you. + + +## Initializing Sentry with a top-level `import` + +Enable the top-level `import` by setting `autoInjectServerSentry`: + +```typescript {filename:nuxt.config.ts} {3} +export default defineNuxtConfig({ + sentry: { + autoInjectServerSentry: 'top-level-import' + }, +}) +``` + +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 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 +``` diff --git a/docs/platforms/javascript/guides/nuxt/manual-setup.mdx b/docs/platforms/javascript/guides/nuxt/manual-setup.mdx index 5b14147ce7ea3..8bbb82de1cf10 100644 --- a/docs/platforms/javascript/guides/nuxt/manual-setup.mdx +++ b/docs/platforms/javascript/guides/nuxt/manual-setup.mdx @@ -125,6 +125,12 @@ dotenv.config(); // ... rest of the file ``` +#### Load Sentry config + +Sentry can only be loaded on the server-side if it is explicitly added via `--import`. + +Refer to the documentation of using `--import` CLI flag for setup instructions. + In the beta state of the Nuxt SDK, some features may not work with certain deployment providers. Check the progress on GitHub: [Compatibility with different Deployment Platforms](https://github.com/getsentry/sentry-javascript/issues/14029) From 5bb1f9dd916feda267bc9b26e713ff6f00abfa77 Mon Sep 17 00:00:00 2001 From: s1gr1d Date: Fri, 6 Dec 2024 15:01:34 +0100 Subject: [PATCH 2/3] change to experimental_entrypointWrappedFunctions --- .../javascript/guides/nuxt/install/dynamic-import.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx index 0232e836ddc06..63e7ab70f55d7 100644 --- a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx @@ -75,7 +75,7 @@ You can also check out the guide for using the follow the ESM instructions. However, if you want to avoid using the `--import` command line option, for example if you have no way of configuring a CLI flag, you can also follow an alternative setup that involves importing the `instrument.mjs` file directly in your application. -This installation method has a fundamental restriction: It only supports limited performance instrumentation. Only basic `http` instrumentation will work, and no DB or framework-specific instrumentation will be available. - -Because of this, we recommend using this only if the `--import` flag is not an option for you. + This installation method has fundamental restrictions: + - It only supports limited performance instrumentation. + - Only basic `http` 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. You need to create a file named `instrument.mjs` that imports and initializes Sentry: diff --git a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx index 205aff0aeda13..2f9358de56f7e 100644 --- a/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/cli-import.mdx @@ -1,28 +1,27 @@ --- title: --import CLI flag (default) sidebar_order: 1 -description: "Learn about using the node --import CLI flag." +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 allows you to preload modules before the application starts. This is the default -way in ESM to load a module before the application starts. +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 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'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 +- **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 a top-level import or a dynamic import instead. ## Initializing Sentry with `--import` -By default, the SDK will add the Sentry server config to the build output (typically `.output/server/sentry.server.config.mjs`). +By default, the SDK will add the Sentry server config to the build output (typically, `.output/server/sentry.server.config.mjs`). ### 1. Adding `--import` to `node` command @@ -42,7 +41,6 @@ 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" } } diff --git a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx index 63e7ab70f55d7..bd5b4cf9d5e70 100644 --- a/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/dynamic-import.mdx @@ -24,13 +24,13 @@ export default defineNuxtConfig({ }) ``` -After setting this, the Sentry Nuxt SDK adds a Rollup plugin which wraps the server entry file with a 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. -The server entry file will look something like this: +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 +// Note: The file may have some imports and code, related to debug IDs Sentry.init({ dsn: "..." }); @@ -44,7 +44,7 @@ Depending on your setup and which version of Nitro is used, the server-side is s The build output **must not** include a regular `import` of the Nitro runtime (e.g. `import './chunks/nitro/nitro.mjs'`). See the ([GitHub issue here](https://github.com/getsentry/sentry-javascript/issues/14514)) for more information. -As a temporary workaround, you can add the following overrides to your application: +As a temporary workaround, you can add the following overrides in your application: ```json {tabTitle:npm} {filename:package.json} "overrides": { @@ -67,16 +67,14 @@ As a temporary workaround, you can add the following overrides to your applicati } ``` -You can also check out the guide for using the CLI flag `--import` or a top-level import as this might be a better choice for you. - +You can also check out the guide for installing the SDK with a CLI flag `--import` or a top-level import. ## 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 `experimental_entrypointWrappedFunctions`: - +If your serverless function has a custom name, you can override it with `experimental_entrypointWrappedFunctions`: ```javascript {filename: nuxt.config.ts} {7} export default defineNuxtConfig({ diff --git a/docs/platforms/javascript/guides/nuxt/install/top-level-import.mdx b/docs/platforms/javascript/guides/nuxt/install/top-level-import.mdx index b6281ea22588a..b07b2d5acd008 100644 --- a/docs/platforms/javascript/guides/nuxt/install/top-level-import.mdx +++ b/docs/platforms/javascript/guides/nuxt/install/top-level-import.mdx @@ -4,20 +4,23 @@ sidebar_order: 2 description: "Learn about how the Nuxt SDK adds a top-level import to the build output." --- -## Understanding top-level `import` +## Understanding Top-level `import` Sentry needs to be initialized before the application starts. If the default way of adding an `--import` CLI flag 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 server entry file. -In this scenario, Sentry is not initialized before application startup, but as early as otherwise possible. +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. +In this case, Sentry isn’t initialized before the app starts, but is set up as early as possible. - This installation method has a fundamental restriction: It only supports limited performance instrumentation. Only basic `http` instrumentation will work, and no DB or framework-specific instrumentation will be available. + This installation method has fundamental restrictions: + - It only supports limited performance instrumentation. + - Only basic `http` instrumentation will work. + - No DB or framework-specific instrumentation will be available. - Because of this, we recommend using this only if the `--import` flag is not an option for you. + We recommend using this only if the `--import` flag is not an option for you. -## Initializing Sentry with a top-level `import` +## Initializing Sentry With a Top-level `import` Enable the top-level `import` by setting `autoInjectServerSentry`: @@ -29,11 +32,11 @@ export default defineNuxtConfig({ }) ``` -By default, the SDK will add the Sentry server config to the build output (typically `.output/server/sentry.server.config.mjs`). +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 server entry file will look something like this: +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 +// Note: The file may have some imports and code, related to debug IDs ``` diff --git a/docs/platforms/javascript/guides/nuxt/manual-setup.mdx b/docs/platforms/javascript/guides/nuxt/manual-setup.mdx index 8bbb82de1cf10..0d2f16b34a98a 100644 --- a/docs/platforms/javascript/guides/nuxt/manual-setup.mdx +++ b/docs/platforms/javascript/guides/nuxt/manual-setup.mdx @@ -127,9 +127,9 @@ dotenv.config(); #### Load Sentry config -Sentry can only be loaded on the server-side if it is explicitly added via `--import`. +Sentry can only be loaded on the server-side by being explicitly added via `--import`. -Refer to the documentation of using `--import` CLI flag for setup instructions. +Check out the `--import` CLI flag docs for setup instructions. In the beta state of the Nuxt SDK, some features may not work with certain deployment providers. Check the progress on GitHub: [Compatibility with different Deployment Platforms](https://github.com/getsentry/sentry-javascript/issues/14029)