Skip to content

Commit b9e6474

Browse files
inventarSarahchargome
authored and
antonpirker
committed
docs(js): Update Nest.js installation method content (#13765)
<!-- Use this checklist to make sure your PR is ready for merge. You may delete any sections you don't need. --> ## DESCRIBE YOUR PR Closes: #13525 - Created an /install section for nestjs (in the project structure) - index page: added a section for Nest.js - CJS: removed content and linked to quick start guide - Nestjs will not display late-initialization.mdx file - updated "@sentry/node" to "@sentry/nestjs" - updated node --import commands for ESM Please also review the installation method pages to see if we need to change anything else for Nest.js! ## IS YOUR CHANGE URGENT? Help us prioritize incoming PRs by letting us know when the change needs to go live. - [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE --> - [ ] Other deadline: <!-- ENTER DATE HERE --> - [ ] None: Not urgent, can wait up to 1 week+ ## SLA - Teamwork makes the dream work, so please add a reviewer to your PRs. - Please give the docs team up to 1 week to review your PR unless you've added an urgent due date to it. Thanks in advance for your help! ## PRE-MERGE CHECKLIST *Make sure you've checked the following before merging your changes:* - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) ## EXTRA RESOURCES - [Sentry Docs contributor guide](https://docs.sentry.io/contributing/) --------- Co-authored-by: Charly Gomez <[email protected]>
1 parent 1c75547 commit b9e6474

File tree

10 files changed

+253
-5
lines changed

10 files changed

+253
-5
lines changed

‎docs/platforms/javascript/common/install/commonjs.mdx

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ supported:
1010
- javascript.hapi
1111
- javascript.hono
1212
- javascript.koa
13-
- javascript.nestjs
1413
---
1514

1615
<Alert>

‎docs/platforms/javascript/common/install/esm-without-import.mdx

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ supported:
1010
- javascript.hapi
1111
- javascript.hono
1212
- javascript.koa
13-
- javascript.nestjs
1413
---
1514

1615
<Alert>

‎docs/platforms/javascript/common/install/esm.mdx

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ supported:
1010
- javascript.hapi
1111
- javascript.hono
1212
- javascript.koa
13-
- javascript.nestjs
1413
---
1514

1615
<Alert>

‎docs/platforms/javascript/common/install/esm__v8.x.mdx

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ supported:
1010
- javascript.hapi
1111
- javascript.hono
1212
- javascript.koa
13-
- javascript.nestjs
1413
noindex: true
1514
---
1615

‎docs/platforms/javascript/common/install/late-initialization.mdx

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,6 @@ supported:
1010
- javascript.hapi
1111
- javascript.hono
1212
- javascript.koa
13-
- javascript.nestjs
1413
---
1514

1615
<Alert>

‎docs/platforms/javascript/guides/nestjs/install/commonjs.mdx

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: CommonJS (CJS)
3+
sidebar_order: 9
4+
description: "Learn about running Sentry in an CJS application."
5+
supported:
6+
- javascript.nestjs
7+
---
8+
9+
<Alert>
10+
Are you unsure if you should use this installation method? Review our
11+
[installation methods](../).
12+
</Alert>
13+
14+
Most node applications today are either written in or compiled to CommonJS (CJS), which uses `require()` to load modules.
15+
Nest.js, by default, transpiles your TypeScript code into CommonJS.
16+
17+
You can follow the installation instructions in the SDK's <PlatformLink to="/">Quick Start guide</PlatformLink>.

‎docs/platforms/javascript/guides/nestjs/install/esm-without-import.mdx

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: ESM Without CLI Flag
3+
sidebar_order: 11
4+
description: "Learn about running Sentry in an ESM application, without the --import flag."
5+
supported:
6+
- javascript.nestjs
7+
---
8+
9+
<Alert>
10+
Are you unsure if you should use this installation method? Review our
11+
[installation methods](../).
12+
</Alert>
13+
14+
When running your application in [ECMAScript Modules](https://nodejs.org/api/esm.html#introduction) (ESM) mode, you'll most likely want to <PlatformLink to="/install/esm">follow the ESM instructions</PlatformLink>. 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.
15+
16+
<Alert level='warning' title='Restrictions of this installation method'>
17+
18+
This installation method has the fundamental restriction that only native Node.js APIs can be instrumented (such as `fetch` and the `http` module).
19+
20+
As a result, the Sentry SDK will **not** capture data from database calls, queues, ORMs, third-party libraries, or other framework-specific data.
21+
22+
We recommend using this only if the `--import` flag is not an option for you.
23+
24+
</Alert>
25+
26+
**Step 1:** Create a file named `instrument.mjs` that imports and initializes Sentry:
27+
28+
```javascript {tabTitle:ESM} {filename: instrument.mjs}
29+
import * as Sentry from "@sentry/nestjs";
30+
31+
// Ensure to call this before importing any other modules!
32+
Sentry.init({
33+
dsn: "___PUBLIC_DSN___",
34+
35+
// Add Tracing by setting tracesSampleRate
36+
// We recommend adjusting this value in production
37+
tracesSampleRate: 1.0,
38+
});
39+
```
40+
41+
**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:
42+
43+
```javascript {filename: main.ts}
44+
// Import this first!
45+
import "./instrument";
46+
47+
// Now import other modules
48+
import { NestFactory } from "@nestjs/core";
49+
// ...
50+
// Your application code goes here
51+
```

‎docs/platforms/javascript/guides/nestjs/install/esm.mdx

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: ESM (MJS)
3+
sidebar_order: 10
4+
description: "Learn about running Sentry in an ESM application."
5+
supported:
6+
- javascript.nestjs
7+
---
8+
9+
<Alert>
10+
Are you unsure if you should use this installation method? Review our
11+
[installation methods](../).
12+
</Alert>
13+
14+
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.
15+
16+
**Step 1:** Create a file named `instrument.mjs` that imports and initializes Sentry:
17+
18+
```javascript {tabTitle:ESM} {filename: instrument.mjs}
19+
import * as Sentry from "@sentry/nestjs";
20+
21+
// Ensure to call this before importing any other modules!
22+
Sentry.init({
23+
dsn: "___PUBLIC_DSN___",
24+
25+
// Add Tracing by setting tracesSampleRate
26+
// We recommend adjusting this value in production
27+
tracesSampleRate: 1.0,
28+
});
29+
```
30+
31+
**Step 2:** Adjust your application's start command to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter:
32+
33+
```bash
34+
# Note: This is only available for Node v18.19.0 onwards.
35+
"start": "--import ./instrument.mjs nest start"
36+
```
37+
38+
If you can't pass the `--import` flag to the Node.js binary, you can alternatively use the `NODE_OPTIONS` environment variable as follows:
39+
40+
```bash
41+
NODE_OPTIONS="--import ./instrument.mjs" npm run start
42+
```
43+
44+
<Alert>We do not support ESM in Node versions before 18.19.0.</Alert>
45+
46+
## Troubleshooting ESM Instrumentation
47+
48+
By default, all packages are automatically wrapped by
49+
[import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle) to
50+
aid instrumenting them.
51+
52+
If `import-in-the-middle` encounters problems wrapping a package, you may see
53+
syntax errors at runtime or logged errors in your console:
54+
55+
```logs
56+
SyntaxError: The requested module '...' does not provide an export named '...'
57+
(node:3368) Error: 'import-in-the-middle' failed to wrap 'file://../../path/to/file.js'
58+
```
59+
60+
To confirm that these errors are caused by `import-in-the-middle`,
61+
disable it by setting `registerEsmLoaderHooks` to false. Note, this will also
62+
disable tracing instrumentation:
63+
64+
```javascript {tabTitle:ESM} {filename: instrument.mjs} {4}
65+
import * as Sentry from "@sentry/nestjs";
66+
67+
Sentry.init({
68+
registerEsmLoaderHooks: false,
69+
});
70+
```

‎docs/platforms/javascript/guides/nestjs/install/esm__v8.x.mdx

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: ESM (MJS)
3+
sidebar_order: 10
4+
description: "Learn about running Sentry in an ESM application."
5+
supported:
6+
- javascript.nestjs
7+
noindex: true
8+
---
9+
10+
<Alert>
11+
Are you unsure if you should use this installation method? Review our
12+
[installation methods](../).
13+
</Alert>
14+
15+
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.
16+
17+
**Step 1:** Create a file named `instrument.mjs` that imports and initializes Sentry:
18+
19+
```javascript {tabTitle:ESM} {filename: instrument.mjs}
20+
import * as Sentry from "@sentry/nestjs";
21+
22+
// Ensure to call this before importing any other modules!
23+
Sentry.init({
24+
dsn: "___PUBLIC_DSN___",
25+
26+
// Add Tracing by setting tracesSampleRate
27+
// We recommend adjusting this value in production
28+
tracesSampleRate: 1.0,
29+
});
30+
```
31+
32+
**Step 2:** Adjust your application's start command to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter:
33+
34+
```bash
35+
# Note: This is only available for Node v18.19.0 onwards.
36+
"start": "--import ./instrument.mjs nest start"
37+
```
38+
39+
If you can't pass the `--import` flag to the Node.js binary, you can alternatively use the `NODE_OPTIONS` environment variable as follows:
40+
41+
```bash
42+
NODE_OPTIONS="--import ./instrument.mjs" npm run start
43+
```
44+
45+
<Alert>We do not support ESM in Node versions before 18.19.0.</Alert>
46+
47+
## Troubleshooting instrumentation
48+
49+
By default, all packages are automatically wrapped by
50+
[import-in-the-middle](https://www.npmjs.com/package/import-in-the-middle) to
51+
aid instrumenting them.
52+
53+
If `import-in-the-middle` encounters problems wrapping a package, you may see
54+
syntax errors at runtime or logged errors in your console:
55+
56+
```logs
57+
SyntaxError: The requested module '...' does not provide an export named '...'
58+
(node:3368) Error: 'import-in-the-middle' failed to wrap 'file://../../path/to/file.js'
59+
```
60+
61+
To confirm that these errors are caused by `import-in-the-middle`,
62+
disable it by setting `registerEsmLoaderHooks` to false. Note, this will also
63+
disable tracing instrumentation:
64+
65+
```javascript {tabTitle:ESM} {filename: instrument.mjs} {4}
66+
import * as Sentry from "@sentry/nestjs";
67+
68+
Sentry.init({
69+
registerEsmLoaderHooks: false,
70+
});
71+
```
72+
73+
If you are starting Sentry via `--import`, you can instruct `import-in-the-middle`
74+
to only wrap packages that Sentry specifically instruments. To do this, you can
75+
set the `onlyIncludeInstrumentedModules` to `true`:
76+
77+
```javascript {tabTitle:ESM} {filename: instrument.mjs} {4-6}
78+
import * as Sentry from "@sentry/nestjs";
79+
80+
Sentry.init({
81+
registerEsmLoaderHooks: {
82+
onlyIncludeInstrumentedModules: true,
83+
},
84+
});
85+
```

‎docs/platforms/javascript/guides/nestjs/install/index.mdx

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Installation Methods
3+
sidebar_order: 1
4+
description: "Review our alternate installation methods for Sentry using Nest.js."
5+
supported:
6+
- javascript.nestjs
7+
---
8+
9+
<PageGrid />
10+
11+
## How To Decide Which Installation Method To Use
12+
13+
Most node applications today are either written in or compiled to CommonJS (CJS), which uses `require()` to load modules.
14+
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).
15+
16+
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).
17+
18+
### My application uses the default Nest.js setup
19+
20+
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.
21+
22+
### My application uses `require`
23+
24+
If you're using `require()` in your application, you should follow the [CommonJS instructions](./commonjs).
25+
26+
### My application uses `import`
27+
28+
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).
29+
30+
If you do not compile your code, you'll need to follow the [ESM instructions](./esm).

0 commit comments

Comments
 (0)