Skip to content

feat(node): Document SEA setup #17752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
logaretm merged 6 commits into from
May 19, 2026
+62 −1
Merged

feat(node): Document SEA setup #17752

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
746ddd1
feat: document sea applications setup
logaretm May 13, 2026
81b104f
fix: added bootstrap compat for node 26
logaretm May 13, 2026
2da352b
fix: address review feedback for SEA docs
logaretm May 19, 2026
e312160
fix: remove unnecessary useCodeCache: false from SEA config
logaretm May 19, 2026
0bb3b0e
fix: revert alert wording
logaretm May 19, 2026
a2221e5
fix: links
logaretm May 19, 2026
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
53 changes: 52 additions & 1 deletion docs/platforms/javascript/common/install/esm-without-import.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,12 @@ This installation method has the fundamental restriction that only native Node.j

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.
We recommend using these setups only if the `--import` flag is not an option for you.
Copy link
Copy Markdown
Collaborator

@inventarSarah inventarSarah May 18, 2026

Choose a reason for hiding this comment

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

You can remove your changes from this alert because it now lives in the "Static import" section


This restriction applies when your application statically imports
`instrument.mjs` from the same ESM module graph. If you use a Node.js Single
Executable Application (SEA), use the <PlatformLink to="/install/esm-without-import/#nodejs-single-executable-applications">SEA
bootstrap setup</PlatformLink> instead.

</Alert>

Expand Down Expand Up @@ -55,3 +60,49 @@ 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 bootstrap imports Sentry first, then imports your real app entrypoint:

```javascript {filename: sea-main.cjs}
(async () => {
await import("./instrument.mjs");
await import("./app.mjs");
})();
```
Comment thread
sentry[bot] marked this conversation as resolved.
Copy link
Copy Markdown
Contributor

@sentry sentry Bot May 19, 2026

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 the bootstrap as its main script and disable code
cache:

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

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 main.

Node.js SEA support is still evolving, including how embedded ESM entrypoints
are configured. 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
View file
Open in desktop
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