Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 58 additions & 1 deletion docs/platforms/javascript/common/install/esm-without-import.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,11 @@ supported:
[installation methods](../).
</Alert>

When running your application in ESM mode, you will 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.

When running your application in ESM mode, you will most likely want to <PlatformLink to="/install/esm">follow the ESM instructions</PlatformLink>. However, if you can't use the `--import` command line option, you can either use [direct imports](#direct-imports) or [SEA bootstrap setup](#nodejs-single-executable-applications) if you are using a Node.js Single Executable Application (SEA).

## Direct Imports


<Alert level='warning' title='Restrictions of this installation method'>

Expand Down Expand Up @@ -55,3 +59,56 @@ import http from "http";

// Your application code goes here
```

## Node.js Single Executable Applications

Node.js Single Executable Applications (SEA) may not load your Sentry instrumentation early enough, so you need to package a small bootstrap file as the SEA main instead of packaging your app entrypoint directly.

The embedded SEA main should only load a filesystem bootstrap file next to the
executable:

```javascript {filename: sea-main.cjs}
const { createRequire } = require("node:module");

createRequire(__filename)("./sea-bootstrap.cjs");
```

The filesystem bootstrap imports Sentry first, then imports your real app
entrypoint:

```javascript {filename: sea-bootstrap.cjs}
async function startApp() {
await import("./instrument.mjs");
await import("./app.mjs");
}

startApp();
```
Comment thread
sentry[bot] marked this conversation as resolved.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The startApp() async function is called without a .catch() block, which can lead to an unhandled promise rejection and crash the application if an import fails.
Severity: MEDIUM

Suggested Fix

Add a .catch() block to the startApp() function call to handle potential promise rejections. This will prevent the application from crashing if a dynamic import fails.

Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location: docs/platforms/javascript/common/install/esm-without-import.mdx#L88

Potential issue: In the `sea-bootstrap.cjs` example code, the `startApp()` async
function is invoked at the top level without any error handling. Since `startApp`
performs dynamic imports, any failure during the import process (e.g., a missing file)
will result in a rejected promise. Without a `.catch()` block to handle this rejection,
the Node.js process will terminate due to an unhandled promise rejection. This affects
users who copy this example code.


Keep your Sentry setup in `instrument.mjs`:

```javascript {tabTitle:ESM} {filename: instrument.mjs}
import * as Sentry from "@sentry/node";

Sentry.init({
dsn: "___PUBLIC_DSN___",
tracesSampleRate: 1.0,
});
```

Then configure SEA to use `sea-main.cjs` as its main script:

```json {filename: sea-config.json}
{
"main": "sea-main.cjs",
"output": "sea-prep.blob",
"disableExperimentalSEAWarning": true,
"useSnapshot": false
}
```

Keep `sea-bootstrap.cjs`, `instrument.mjs`, and `app.mjs` available on the filesystem next to the executable.

This setup lets the Sentry SDK register ESM instrumentation hooks before your application imports instrumented modules, such as Express or database clients. Your instrumentation file and app entrypoint can stay ESM. The verified bootstrap pattern shown here uses CommonJS only for the small SEA entry files.

Node.js SEA support is still evolving, including how embedded ESM entrypoints and module loading are configured. The embedded SEA main may not be able to load filesystem modules with `import()` directly, so the example above uses `module.createRequire()` to bridge from the embedded main to a normal filesystem bootstrap. The important requirement is startup order: load Sentry before loading the application modules you want Sentry to instrument.
4 changes: 4 additions & 0 deletions docs/platforms/javascript/common/install/esm.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,10 @@ If it is not possible for you to pass the `--import` flag to the Node.js binary,
NODE_OPTIONS="--import ./instrument.mjs" npm run start
```

If you're building a Node.js Single Executable Application (SEA) and can't rely
on `--import` or `NODE_OPTIONS`, use the <PlatformLink to="/install/esm-without-import/#nodejs-single-executable-applications">SEA
bootstrap setup</PlatformLink> instead.

We do not support ESM in Node versions before 18.19.0.

## Troubleshooting instrumentation
Expand Down
Loading