Potentially confusing docs for ESM

[Xhale1]

Hello hello! I'm hoping to get a bit of clarification on a specific part of Sentry's docs for getting started with nodejs. In this section Sentry states that when using ESM you should import your instrument file before anything else:

// Import this first!
import "./instrument";

I assume this is specifically for projects written in ESM, not necessarily run with ESM. The docs go on to specify that you should use a node --import flag when running with ESM to ensure Sentry is setup before any other modules are imported.

Does that mean the import "./instrument"; code is no longer necessary / could potentially lead to two instances of Sentry's SDK being initialized?

[lforst]

@Xhale1 I agree with you. @mydea I remember we discussed this pretty heavily back when we released v8. Is there a reason we wrote the docs like this?

[mydea]

Yeah, all of this is a bit tricky and hard to document.

Our reasoning when writing this was that most people run their apps in CJS mode, so this is what we optimize for in the getting started guide. But I agree that we can add more clarity on this in the ESM code block in the getting started section. e.g. a minimum change could be something along these lines:

// Import this first!
import "./instrument";
// Note: If you run your application as ESM application, you do not need this.
// Instead, you'll need to initialize Sentry in `--import`. See below for details on this.

// Now import other modules
import http from "http";

// Your application code goes here

[Xhale1]

I think that clarification helps a lot!

It seems like the tricky part is the distinction between writing ESM code vs running in ESM.