Installation Methods for Fastify

How To Decide Which Installation Method To Use

The SDK has to wrap the modules your application uses before your application imports them. How you arrange that is the only difference between the methods below. --import works for both ESM and CommonJS applications, so the module system your application uses no longer decides the method.

Load Your Instrument File With --import (Recommended)

Put Sentry.init() in an instrument file and load it with the --import flag:

node --import ./instrument.mjs app.mjs

node --import ./instrument.mjs app.mjs

This runs Sentry.init() before any of your application's modules load, so every instrumented library is wrapped and every error during startup is captured. Use this unless one of the cases below applies to you.

--import works for CommonJS applications too, with an instrument.js file:

node --import ./instrument.js app.js

node --import ./instrument.js app.js

Note that --require is no longer supported for initialization.

Bundler Plugin and a Top-Level Import

If you build your server with a bundler, instrument your dependencies at build time with the Sentry bundler plugin and import instrument.mjs at the top of your entry file. Because the plugin bakes the instrumentation into your bundle, a top-level import is enough and you don't need a flag on the Node.js binary. See With a Bundler.

If you can't use a bundler, a top-level import on its own isn't equivalent to --import, because ESM evaluates every import in a file before it runs the first line of that file. See Deferred Entrypoint for an alternative way to run your application in this case.

Prepare the instrumentation with --import and Initialize Later

If you can't call Sentry.init() at startup, for example because you fetch your DSN from an external source, --import the instrumentation early and call Sentry.init() at a later point:

node --import @sentry/node/import main.mjs

node --import @sentry/node/import main.mjs

See Late Initialization.