diff --git a/docs/platforms/javascript/common/install/commonjs.mdx b/docs/platforms/javascript/common/install/commonjs.mdx index b82ef45c201e0..978d93e2ea363 100644 --- a/docs/platforms/javascript/common/install/commonjs.mdx +++ b/docs/platforms/javascript/common/install/commonjs.mdx @@ -10,7 +10,6 @@ supported: - javascript.hapi - javascript.hono - javascript.koa - - javascript.nestjs --- diff --git a/docs/platforms/javascript/common/install/esm-without-import.mdx b/docs/platforms/javascript/common/install/esm-without-import.mdx index aafcf6808af15..f7357b5f93e2a 100644 --- a/docs/platforms/javascript/common/install/esm-without-import.mdx +++ b/docs/platforms/javascript/common/install/esm-without-import.mdx @@ -10,7 +10,6 @@ supported: - javascript.hapi - javascript.hono - javascript.koa - - javascript.nestjs --- diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx index 8e3adbc8b768f..d2d80d8145077 100644 --- a/docs/platforms/javascript/common/install/esm.mdx +++ b/docs/platforms/javascript/common/install/esm.mdx @@ -10,7 +10,6 @@ supported: - javascript.hapi - javascript.hono - javascript.koa - - javascript.nestjs --- diff --git a/docs/platforms/javascript/common/install/esm__v8.x.mdx b/docs/platforms/javascript/common/install/esm__v8.x.mdx index 89247a00173ac..fb850ab562d98 100644 --- a/docs/platforms/javascript/common/install/esm__v8.x.mdx +++ b/docs/platforms/javascript/common/install/esm__v8.x.mdx @@ -10,7 +10,6 @@ supported: - javascript.hapi - javascript.hono - javascript.koa - - javascript.nestjs noindex: true --- diff --git a/docs/platforms/javascript/common/install/late-initialization.mdx b/docs/platforms/javascript/common/install/late-initialization.mdx index 1eb13be50ea60..1362f0af7741a 100644 --- a/docs/platforms/javascript/common/install/late-initialization.mdx +++ b/docs/platforms/javascript/common/install/late-initialization.mdx @@ -10,7 +10,6 @@ supported: - javascript.hapi - javascript.hono - javascript.koa - - javascript.nestjs --- diff --git a/docs/platforms/javascript/guides/nestjs/install/commonjs.mdx b/docs/platforms/javascript/guides/nestjs/install/commonjs.mdx new file mode 100644 index 0000000000000..72438c712846d --- /dev/null +++ b/docs/platforms/javascript/guides/nestjs/install/commonjs.mdx @@ -0,0 +1,17 @@ +--- +title: CommonJS (CJS) +sidebar_order: 9 +description: "Learn about running Sentry in an CJS application." +supported: + - javascript.nestjs +--- + + + Are you unsure if you should use this installation method? Review our + [installation methods](../). + + +Most node applications today are either written in or compiled to CommonJS (CJS), which uses `require()` to load modules. +Nest.js, by default, transpiles your TypeScript code into CommonJS. + +You can follow the installation instructions in the SDK's Quick Start guide. diff --git a/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx b/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx new file mode 100644 index 0000000000000..3c31674c680bb --- /dev/null +++ b/docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx @@ -0,0 +1,51 @@ +--- +title: ESM Without CLI Flag +sidebar_order: 11 +description: "Learn about running Sentry in an ESM application, without the --import flag." +supported: + - javascript.nestjs +--- + + + Are you unsure if you should use this installation method? Review our + [installation methods](../). + + +When running your application in [ECMAScript Modules](https://nodejs.org/api/esm.html#introduction) (ESM) mode, you'll most likely want to 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 the fundamental restriction that only native Node.js APIs can be instrumented (such as `fetch` and the `http` module). + +As a result, the Sentry SDK will **not** capture data from database calls, queues, ORMs, third-party libraries, or other framework-specific data. + +We recommend using this only if the `--import` flag is not an option for you. + + + +**Step 1:** Create a file named `instrument.mjs` that imports and initializes Sentry: + +```javascript {tabTitle:ESM} {filename: instrument.mjs} +import * as Sentry from "@sentry/nestjs"; + +// Ensure to call this before importing any other modules! +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + // Add Tracing by setting tracesSampleRate + // We recommend adjusting this value in production + tracesSampleRate: 1.0, +}); +``` + +**Step 2:** Import the `instrument.mjs` file before importing any other modules in your in the `main.ts` file of your application. This ensures that Sentry can automatically instrument all modules in your application: + +```javascript {filename: main.ts} +// Import this first! +import "./instrument"; + +// Now import other modules +import { NestFactory } from "@nestjs/core"; +// ... +// Your application code goes here +``` diff --git a/docs/platforms/javascript/guides/nestjs/install/esm.mdx b/docs/platforms/javascript/guides/nestjs/install/esm.mdx new file mode 100644 index 0000000000000..9ba9ba454e9a0 --- /dev/null +++ b/docs/platforms/javascript/guides/nestjs/install/esm.mdx @@ -0,0 +1,70 @@ +--- +title: ESM (MJS) +sidebar_order: 10 +description: "Learn about running Sentry in an ESM application." +supported: + - javascript.nestjs +--- + + + Are you unsure if you should use this installation method? Review our + [installation methods](../). + + +When running your application in [ECMAScript Modules](https://nodejs.org/api/esm.html#introduction) (ESM) mode, you can't use `require()` to load modules. Instead, you have to use the `--import` command line options to load a module before the application starts. + +**Step 1:** Create a file named `instrument.mjs` that imports and initializes Sentry: + +```javascript {tabTitle:ESM} {filename: instrument.mjs} +import * as Sentry from "@sentry/nestjs"; + +// Ensure to call this before importing any other modules! +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + // Add Tracing by setting tracesSampleRate + // We recommend adjusting this value in production + tracesSampleRate: 1.0, +}); +``` + +**Step 2:** Adjust your application's start command to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter: + +```bash +# Note: This is only available for Node v18.19.0 onwards. +"start": "--import ./instrument.mjs nest start" +``` + +If you can't pass the `--import` flag to the Node.js binary, you can alternatively use the `NODE_OPTIONS` environment variable as follows: + +```bash +NODE_OPTIONS="--import ./instrument.mjs" npm run start +``` + +We do not support ESM in Node versions before 18.19.0. + +## Troubleshooting ESM Instrumentation + +By default, all packages are automatically wrapped by +[import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle) to +aid instrumenting them. + +If `import-in-the-middle` encounters problems wrapping a package, you may see +syntax errors at runtime or logged errors in your console: + +```logs +SyntaxError: The requested module '...' does not provide an export named '...' +(node:3368) Error: 'import-in-the-middle' failed to wrap 'file://../../path/to/file.js' +``` + +To confirm that these errors are caused by `import-in-the-middle`, +disable it by setting `registerEsmLoaderHooks` to false. Note, this will also +disable tracing instrumentation: + +```javascript {tabTitle:ESM} {filename: instrument.mjs} {4} +import * as Sentry from "@sentry/nestjs"; + +Sentry.init({ + registerEsmLoaderHooks: false, +}); +``` diff --git a/docs/platforms/javascript/guides/nestjs/install/esm__v8.x.mdx b/docs/platforms/javascript/guides/nestjs/install/esm__v8.x.mdx new file mode 100644 index 0000000000000..ad5ef10d12b37 --- /dev/null +++ b/docs/platforms/javascript/guides/nestjs/install/esm__v8.x.mdx @@ -0,0 +1,85 @@ +--- +title: ESM (MJS) +sidebar_order: 10 +description: "Learn about running Sentry in an ESM application." +supported: + - javascript.nestjs +noindex: true +--- + + + Are you unsure if you should use this installation method? Review our + [installation methods](../). + + +When running your application in [ECMAScript Modules](https://nodejs.org/api/esm.html#introduction) (ESM) mode, you can't use `require()` to load modules. Instead, you have to use the `--import` command line options to load a module before the application starts. + +**Step 1:** Create a file named `instrument.mjs` that imports and initializes Sentry: + +```javascript {tabTitle:ESM} {filename: instrument.mjs} +import * as Sentry from "@sentry/nestjs"; + +// Ensure to call this before importing any other modules! +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + // Add Tracing by setting tracesSampleRate + // We recommend adjusting this value in production + tracesSampleRate: 1.0, +}); +``` + +**Step 2:** Adjust your application's start command to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter: + +```bash +# Note: This is only available for Node v18.19.0 onwards. +"start": "--import ./instrument.mjs nest start" +``` + +If you can't pass the `--import` flag to the Node.js binary, you can alternatively use the `NODE_OPTIONS` environment variable as follows: + +```bash +NODE_OPTIONS="--import ./instrument.mjs" npm run start +``` + +We do not support ESM in Node versions before 18.19.0. + +## Troubleshooting instrumentation + +By default, all packages are automatically wrapped by +[import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle) to +aid instrumenting them. + +If `import-in-the-middle` encounters problems wrapping a package, you may see +syntax errors at runtime or logged errors in your console: + +```logs +SyntaxError: The requested module '...' does not provide an export named '...' +(node:3368) Error: 'import-in-the-middle' failed to wrap 'file://../../path/to/file.js' +``` + +To confirm that these errors are caused by `import-in-the-middle`, +disable it by setting `registerEsmLoaderHooks` to false. Note, this will also +disable tracing instrumentation: + +```javascript {tabTitle:ESM} {filename: instrument.mjs} {4} +import * as Sentry from "@sentry/nestjs"; + +Sentry.init({ + registerEsmLoaderHooks: false, +}); +``` + +If you are starting Sentry via `--import`, you can instruct `import-in-the-middle` +to only wrap packages that Sentry specifically instruments. To do this, you can +set the `onlyIncludeInstrumentedModules` to `true`: + +```javascript {tabTitle:ESM} {filename: instrument.mjs} {4-6} +import * as Sentry from "@sentry/nestjs"; + +Sentry.init({ + registerEsmLoaderHooks: { + onlyIncludeInstrumentedModules: true, + }, +}); +``` diff --git a/docs/platforms/javascript/guides/nestjs/install/index.mdx b/docs/platforms/javascript/guides/nestjs/install/index.mdx new file mode 100644 index 0000000000000..eedeb840fe395 --- /dev/null +++ b/docs/platforms/javascript/guides/nestjs/install/index.mdx @@ -0,0 +1,30 @@ +--- +title: Installation Methods +sidebar_order: 1 +description: "Review our alternate installation methods for Sentry using Nest.js." +supported: + - javascript.nestjs +--- + + + +## How To Decide Which Installation Method To Use + +Most node applications today are either written in or compiled to CommonJS (CJS), which uses `require()` to load modules. +Our recommended installation method when using CommonJS is to require the `instrument.js` file at the top of your application. However, if your application is run in [ECMAScript Modules](https://nodejs.org/api/esm.html#introduction) (ESM) mode, this will not work, in which case you can follow the [ESM docs](./esm). + +Note that even if your application is written in ESM (using `import`), it may still be _run_ in CJS. In this case, you should follow the [CommonJS instructions](./commonjs). + +### My application uses the default Nest.js setup + +Nest.js transpiles to CJS by default, so you should follow the [CommonJS installation instructions](./commonjs). Keep reading if you have a more customized application or build setup. + +### My application uses `require` + +If you're using `require()` in your application, you should follow the [CommonJS instructions](./commonjs). + +### My application uses `import` + +If you're using `import` in your application, your installation method depends on how your application is _run_. If you compile your application (for example, into a `/dist` folder or similar) before running it, you need to check how the compiled code looks like. Is the compiled code using `require`? Then you should follow the [CommonJS instructions](./commonjs). If the compiled code is using `import`, you should follow the [ESM instructions](./esm). + +If you do not compile your code, you'll need to follow the [ESM instructions](./esm).