fix(node): Update ESM instruction with --import @sentry/node/import #10028
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
Bundle ReportChanges will decrease total bundle size by 12 bytes ⬇️
|
andreiborza
force-pushed
the
ab/esm-loader-hook
branch
from
ef672ec
to
c0a7fa4
Compare
lizokm
approved these changes
May 14, 2024
| When running your application in 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: | ||
|
|
||
| Adjust the Node.js call for your application to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter and point it at `instrument.js`, which contains your `Sentry.init()` code: | ||
| When running your application in ESM mode, you need to pass an [--import](https://nodejs.org/api/cli.html#--importmodule) command line option to register the SDK's ESM module loader so that it can properly instrument libraries. |
There was a problem hiding this comment.
Suggested change
| When running your application in ESM mode, you need to pass an [--import](https://nodejs.org/api/cli.html#--importmodule) command line option to register the SDK's ESM module loader so that it can properly instrument libraries. | |
| Most node applications today are either written in CommonJS (CJS), or compiled to CJS before being ran. While CommonJS uses `require()` to load modules, we recommend using the `instrument.js` file at the top of your application installation method instead. | |
| However, if your application runs in ESM mode, this method won't work unless you run your application with `--import @sentry/node/import`. Note, that even if your application is written in ESM (using `import`), it may still be _run_ in CJS. (Almost all applications written in TypeScript are compiled to CJS before being ran, for example.) If this is the case, follow the [CommonJS instructions](../commonjs). | |
| ## How to Run Your Application | |
| To run your application in ESM mode, you'll need to pass an [--import](https://nodejs.org/api/cli.html#--importmodule) command line option like the one below to register the SDK's ESM module loader so that it can properly instrument libraries. |
Comment on lines
+19
to
+21
| <Alert level="warning"> | ||
| We do not support ESM in Node versions before 18.19.0. | ||
| </Alert> |
There was a problem hiding this comment.
Suggested change
| <Alert level="warning"> | |
| We do not support ESM in Node versions before 18.19.0. | |
| </Alert> | |
| <Alert level="warning"> | |
| We don't support ESM in any versions of Node before 18.19.0. | |
| </Alert> |
| We do not support ESM in Node versions before 18.19.0. | ||
| <Alert level="warning"> | ||
| We do not support ESM in Node versions before 18.19.0. | ||
| </Alert> | ||
|
|
||
| ## When to use this |
There was a problem hiding this comment.
Suggested change
| ## When to use this |
I think this whole section makes more sense as an introduction at the top of the page.
| We do not support ESM in Node versions before 18.19.0. | ||
| <Alert level="warning"> | ||
| We do not support ESM in Node versions before 18.19.0. | ||
| </Alert> | ||
|
|
||
| ## When to use this | ||
|
|
||
| Most node applications today are either written in CommonJS (CJS), or compiled to CJS before running them. |
There was a problem hiding this comment.
Suggested change
| Most node applications today are either written in CommonJS (CJS), or compiled to CJS before running them. |
|
|
||
| ## When to use this | ||
|
|
||
| Most node applications today are either written in CommonJS (CJS), or compiled to CJS before running them. | ||
| CommonJS 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 ESM mode, this will not work. In this case, you can follow the [ESM docs](./esm). | ||
| CommonJS 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 ESM mode, this will not work without running your application with `--import @sentry/node/import`. |
There was a problem hiding this comment.
Suggested change
| CommonJS 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 ESM mode, this will not work without running your application with `--import @sentry/node/import`. |
|
|
||
| Note that even if your application is written in ESM (using `import`), it may still be _run_ in CJS. For example, almost all applications written in TypeScript are compiled to CJS before running them. In this case, you should follow the CommonJS instructions. | ||
| Note that even if your application is written in ESM (using `import`), it may still be _run_ in CJS. For example, almost all applications written in TypeScript are compiled to CJS before running them. In this case, you should follow the [CommonJS instructions](../commonjs). |
There was a problem hiding this comment.
Suggested change
| Note that even if your application is written in ESM (using `import`), it may still be _run_ in CJS. For example, almost all applications written in TypeScript are compiled to CJS before running them. In this case, you should follow the [CommonJS instructions](../commonjs). |
|
We decided not to proceed with this approach, thanks for the review @lizokm. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This has been a regression from the previous version of the docs where we mentioned calling node with
--loader @sentry/node/import.Node itself marks
--loaderas experimental and suggests to use--importinstead.Ref: getsentry/sentry-javascript#12033