|
| 1 | +--- |
| 2 | +title: Initialization Methods |
| 3 | +description: "Review our alternate ways to initialize and run Sentry." |
| 4 | +supported: |
| 5 | + - javascript.node |
| 6 | + - javascript.koa |
| 7 | + - javascript.connect |
| 8 | + - javascript.fastify |
| 9 | + - javascript.express |
| 10 | +--- |
| 11 | + |
| 12 | +The Sentry Node.js SDK can be initialized in multiple ways. Read this page to figure out which one to use. |
| 13 | + |
| 14 | +## How To Decide Which Method To Use |
| 15 | + |
| 16 | +You can initialize the SDK by either |
| 17 | + |
| 18 | +- Using the `--require` (CJS) or `--import` (ESM) flags to import a dedicated file to initialize the SDK (recommended) |
| 19 | +- Importing a dedicated file to initialize Sentry from within your application |
| 20 | + |
| 21 | +### `--require` Or `--import` |
| 22 | + |
| 23 | +Using [--require](https://nodejs.org/api/cli.html#-r---require-module) or [--import](https://nodejs.org/api/cli.html#--importmodule) guarantees that Sentry is imported and initialized before any other modules in your application, which is necessary for the SDK to work properly. |
| 24 | + |
| 25 | +```bash |
| 26 | +# If you are using CommonJS (CJS) |
| 27 | +node --require ./instrument.js app.js |
| 28 | + |
| 29 | +# If you are using ECMAScript Modules (ESM) |
| 30 | +# Note: This is only available for Node v18.19.0 onwards. |
| 31 | +node --import ./instrument.mjs app.mjs |
| 32 | +``` |
| 33 | + |
| 34 | +In some situations however, it may not be possible for you to use these flags: |
| 35 | + |
| 36 | +- **No access to Node.js arguments**: There are many ways of running Node.js and it may not be possible for you to change the runtime flags due to technical or organizational limitations. |
| 37 | +- **Old Node.js versions**: If you are using ECMAScript modules (ESM), you must load your dedicated Sentry initialization file with the `--import` flag. This flag was only introduced in Node.js v18.18.0 and onwards. |
| 38 | + |
| 39 | +If you find yourself in one of these situations, you can evaluate simply importing your Sentry initialization file with an import statement inside your application instead. |
| 40 | + |
| 41 | +### Importing The Sentry Initialization File Directly |
| 42 | + |
| 43 | +As an alternative to the `--require` or `--import` flags, you can simply import your Sentry initialization file directly from your application. |
| 44 | +**Please note that this is not recommended** since `Sentry.init()` should be run before any `import` or `require` statements. |
| 45 | +The Sentry SDK depends on import ordering for instrumenting native and third-party modules. |
| 46 | +We discourage directly importing the initialization file since import ordering is error-prone or can be flagged and mistakenly auto-fixed by linters or changed by code formatters. |
| 47 | + |
| 48 | +```javascript {tabTitle:CommonJS} |
| 49 | +// Ensure to require this before requiring any other modules! |
| 50 | +require("./instrument.js"); |
| 51 | + |
| 52 | +// http and other libraries are only instrumented |
| 53 | +// if required _after_ Sentry has been initialized |
| 54 | +const http = require("http"); |
| 55 | +``` |
| 56 | + |
| 57 | +```javascript {tabTitle:ESM} |
| 58 | +// Ensure to import this before importing any other modules! |
| 59 | +import "./instrument.js"; |
| 60 | + |
| 61 | +// http and other libraries are only instrumented |
| 62 | +// if imported _after_ Sentry has been initialized |
| 63 | +import http from "http"; |
| 64 | +``` |
| 65 | + |
| 66 | +If you are using ESM, you additionally need to pass a `--loader` flag, registering the SDKs ESM module loader, so that the SDK can properly instrument libraries: |
| 67 | + |
| 68 | +```bash |
| 69 | +node --loader @sentry/node/loader app.mjs |
| 70 | +``` |
0 commit comments