diff --git a/docs/platforms/javascript/common/best-practices/index.mdx b/docs/platforms/javascript/common/best-practices/index.mdx index 71f60ed3a60a6..4d8f3ee8fcc16 100644 --- a/docs/platforms/javascript/common/best-practices/index.mdx +++ b/docs/platforms/javascript/common/best-practices/index.mdx @@ -1,7 +1,7 @@ --- title: Special Use Cases description: "Learn how to set up Sentry for several specific use cases with these best practice guides." -sidebar_order: 6 +sidebar_order: 7 notSupported: - javascript.node - javascript.aws-lambda diff --git a/docs/platforms/javascript/common/data-management/index.mdx b/docs/platforms/javascript/common/data-management/index.mdx index ff50566053576..353f0ebb67095 100644 --- a/docs/platforms/javascript/common/data-management/index.mdx +++ b/docs/platforms/javascript/common/data-management/index.mdx @@ -1,7 +1,7 @@ --- title: Data Management description: Learn about different ways to scrub data within your SDK before it gets sent to Sentry. -sidebar_order: 7 +sidebar_order: 8 --- diff --git a/docs/platforms/javascript/common/deployment-provider-setup/general.mdx b/docs/platforms/javascript/common/deployment-provider-setup/general.mdx new file mode 100644 index 0000000000000..572fbc39c9626 --- /dev/null +++ b/docs/platforms/javascript/common/deployment-provider-setup/general.mdx @@ -0,0 +1,97 @@ +--- +title: General +sidebar_order: 1 +description: "Learn about the general deployment setup when using Sentry." +supported: + - javascript.nuxt +--- + + + Nuxt compiles all your code for the client and server side to ECMAScript modules (ESM) syntax ([learn more about ESM and Nuxt](https://nuxt.com/docs/guide/concepts/esm)). + + +Adding Sentry on the server-side for a project in ESM syntax is different from adding Sentry to a project in CommonJS (CJS) syntax. +The Sentry initialization code needs to be loaded first when the application starts. +Preloading the Sentry server config file can be done with the Node [`--import`](https://nodejs.org/api/cli.html#--importmodule) CLI flag when starting the application. + +Internally, Sentry uses a specific ESM loader hook "[import-in-the-middle/hook.mjs](https://www.npmjs.com/package/import-in-the-middle)" which is +automatically added when you add the Sentry server-side config file with `--import`. This will automatically instrument all modules in your application. + +## Setup Sentry Server Config + +As described above, there are some prerequisites for adding Sentry to a Nuxt project in ESM syntax: + +1. The possibility to add the node `--import` CLI flag. +2. Knowing the correct path to your Sentry server config file within your deployment environment (to add the path to the `--import` CLI flag). +3. The `hook.mjs` file is available under `node_modules/import-in-the-middle/hook.mjs` wherever your server-side code is executed. +4. Running Node.js version 18.19.0 or higher (support for `--import`). + +### Adding the `--import` CLI flag + +You can either add the flag directly to the `node` command when starting the application: + +```bash +node --import ./path/to/sentry-server-config.mjs ./path/to/index.mjs +``` + +or use the `NODE_OPTIONS` environment variable: + +```bash +NODE_OPTIONS="--import ./path/to/sentry-server-config.mjs" node ./path/to/index.mjs +``` + +If modifying the `node` command is not possible, you can also add the `NODE_OPTIONS` environment variable wherever you can set environment variables within your deployment environment. +Make sure that this variable is only available during server runtime (not during build time). + +### `import-in-the-middle/hook.mjs` is available + +Usually, the file `node_modules/import-in-the-middle/hook.mjs` is automatically available when installing dependencies. +However, some deployment providers use custom node bundlers that might not include all `node_modules` in order to save storage. +This is often done by tracing the node files and only including the necessary dependencies. Since Sentry has to include the `hook.mjs` file internally with `module.register()` it might not be discovered by some bundlers and therefore not included. +If you get a warning that the `hook.mjs` file is not found, please report this in [the Sentry JS GitHub repo](https://github.com/getsentry/sentry-javascript/issues) or file an issue at your deployment provider. + +Nitro (which is used by Nuxt and SolidStart on the server side) uses [`@vercel/nft`](https://github.com/vercel/nft) during the build. `@vercel/nft` includes files that are added with `module.register()` from version 0.27.4 onwards. +In case you get a runtime error along the lines `Cannot find module '/node_modules/import-in-the-middle/hook.mjs'`, make sure to add a resolution (yarn) or an override (npm/pnpm) for `@vercel/nft`: + +```json {tabTitle:yarn} {filename: package.json} +{ + "resolutions": { + "@vercel/nft": "^0.27.4" + } +} +``` + +```json {tabTitle:npm/pnpm} {filename: package.json} +{ + "overrides": { + "@vercel/nft": "^0.27.4" + } +} +``` + +## Setup other environment variables + +In case you are using environment variables in your project to set up Sentry don't forget to also add them inside your deployment environment: + +```bash +SENTRY_DSN="___PUBLIC_DSN___" +SENTRY_AUTH_TOKEN="___ORG_AUTH_TOKEN___" +``` + + + +## Exclude modules from import-in-the-middle + +As all packages are wrapped under the hood by [import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle), you might run into issues with certain packages. If you run into a problem with a package, you can skip instrumentation for it by configuring `registerEsmLoaderHooks` in your `Sentry.init()` config. + +```javascript {tabTitle:ESM} {filename: instrument.mjs} +import * as Sentry from "@sentry/node"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___", + registerEsmLoaderHooks: { + // Provide a list of package names to exclude from instrumentation + exclude: ["package-name"], + }, +}); +``` diff --git a/docs/platforms/javascript/common/deployment-provider-setup/index.mdx b/docs/platforms/javascript/common/deployment-provider-setup/index.mdx new file mode 100644 index 0000000000000..6a8d490b532eb --- /dev/null +++ b/docs/platforms/javascript/common/deployment-provider-setup/index.mdx @@ -0,0 +1,9 @@ +--- +title: Deployment Provider Setup +sidebar_order: 4 +description: "Review our alternate installation methods." +supported: + - javascript.nuxt +--- + + diff --git a/docs/platforms/javascript/common/deployment-provider-setup/netlify.mdx b/docs/platforms/javascript/common/deployment-provider-setup/netlify.mdx new file mode 100644 index 0000000000000..98563383268e9 --- /dev/null +++ b/docs/platforms/javascript/common/deployment-provider-setup/netlify.mdx @@ -0,0 +1,50 @@ +--- +title: Netlify +sidebar_order: 10 +description: "Learn about running Sentry when deploying to Netlify." +supported: + - javascript.nuxt +--- + + + Deploying on Netlify is still experimental. Currently, not all Sentry features are supported on the server-side. Only your frontend will be monitored. + + + + Before approaching the steps below, read the general documentation around setting up Sentry on a deployment provider to get quick general overview of the process. + This page only shows Netlify-specific steps. + + +## Approach 1: Adding the `--import` flag + + + The server-side of Nuxt is deployed as a Netlify Function. So make sure to scope the environment variable `NODE_OPTIONS` to "Functions". + The path to the function is depending on your setup. When building the preset locally, the file is available at: `.netlify/functions-internal/server/sentry.server.config.mjs`. + + + The docs for this are still vague and we will update them as soon as we know more about which exact path to use for the `--import` flag. + + + + + + +## Approach 2: Enable `experimental_basicServerTracing` + + +Enabling `experimental_basicServerTracing` can be used when adding the node option `--import` does not work. This however only comes with limited tracing functionality because Sentry server config is not **pre**loaded with `--import`. + + + Enabling this option will automatically import the Sentry server config at the top of the server entry file (server entry: `.netlify/functions-internal/server/server.mjs`). + + ```javascript {tabTitle: Nuxt Config} {filename: nuxt.config.ts} + export default defineNuxtConfig({ + sentry: { + // ... other options + experimental_basicServerTracing: true + }, + }) + ``` + + + diff --git a/docs/platforms/javascript/common/enriching-events/index.mdx b/docs/platforms/javascript/common/enriching-events/index.mdx index a96a76ffdf3d0..217e4e29bce68 100644 --- a/docs/platforms/javascript/common/enriching-events/index.mdx +++ b/docs/platforms/javascript/common/enriching-events/index.mdx @@ -1,7 +1,7 @@ --- title: Enriching Events description: Add additional context to your events to make them easier to debug. -sidebar_order: 5 +sidebar_order: 6 --- diff --git a/docs/platforms/javascript/common/usage/index.mdx b/docs/platforms/javascript/common/usage/index.mdx index 3858ed86c8b35..59c6c6bfd197d 100644 --- a/docs/platforms/javascript/common/usage/index.mdx +++ b/docs/platforms/javascript/common/usage/index.mdx @@ -1,7 +1,7 @@ --- title: Capturing Errors and Events description: "Learn how to use the SDK to manually capture errors and other events." -sidebar_order: 4 +sidebar_order: 5 --- Sentry's SDK hooks into your runtime environment and automatically reports errors, uncaught exceptions, and unhandled rejections as well as other types of errors depending on the platform. diff --git a/docs/platforms/javascript/guides/nuxt/features/index.mdx b/docs/platforms/javascript/guides/nuxt/features/index.mdx index 45d97a177d706..5ceac63ace515 100644 --- a/docs/platforms/javascript/guides/nuxt/features/index.mdx +++ b/docs/platforms/javascript/guides/nuxt/features/index.mdx @@ -1,7 +1,7 @@ --- title: Vue Features description: "Learn how to exposes features for first class integration with Vue with Sentry's Nuxt SDK." -sidebar_order: 4 +sidebar_order: 5 --- The Sentry Nuxt SDK offers Vue-specific features for first class integration with the framework. diff --git a/includes/common-imgs/img/netlify-env-variable.png b/includes/common-imgs/img/netlify-env-variable.png new file mode 100644 index 0000000000000..6aca919ff9d71 Binary files /dev/null and b/includes/common-imgs/img/netlify-env-variable.png differ diff --git a/includes/common-imgs/netlify-env-variable.md b/includes/common-imgs/netlify-env-variable.md new file mode 100644 index 0000000000000..5c9158eeb7c9b --- /dev/null +++ b/includes/common-imgs/netlify-env-variable.md @@ -0,0 +1 @@ +![Setting up scoped environment variables in Netlify](./img/netlify-env-variable.png)