From d86fd1aff8cd7987e507b13687b8f253105bb636 Mon Sep 17 00:00:00 2001 From: Francesco Novy Date: Thu, 16 May 2024 16:09:35 +0200 Subject: [PATCH] feat(js): Add docs to use SDK with ESM without `--import` (#10053) --- .../javascript/common/install/commonjs.mdx | 11 ++++ .../common/install/esm-without-import.mdx | 54 +++++++++++++++++++ .../javascript/common/install/esm.mdx | 29 +++++++--- .../javascript/guides/fastify/index.mdx | 4 +- 4 files changed, 87 insertions(+), 11 deletions(-) create mode 100644 docs/platforms/javascript/common/install/esm-without-import.mdx diff --git a/docs/platforms/javascript/common/install/commonjs.mdx b/docs/platforms/javascript/common/install/commonjs.mdx index efe45f7d831ad..a6284ec4645c0 100644 --- a/docs/platforms/javascript/common/install/commonjs.mdx +++ b/docs/platforms/javascript/common/install/commonjs.mdx @@ -10,7 +10,18 @@ supported: - javascript.koa --- + + Are you unsure if you should use this installation method? Review our + [installation methods](../). + + Most node applications today are either written in CommonJS (CJS), or compiled to CJS before running them. CommonJS uses `require()` to load modules. Our recommended installation method when using CommonJS is to require the `instrument.js` file at the top of your application. +You need to create a file named `instrument.js` that imports and initializes Sentry: + + + +You need to require or import the `instrument.js` file before requiring any other modules in your application. This is necessary to ensure that Sentry can automatically instrument all modules in your application: + diff --git a/docs/platforms/javascript/common/install/esm-without-import.mdx b/docs/platforms/javascript/common/install/esm-without-import.mdx new file mode 100644 index 0000000000000..7be4cc7286ad4 --- /dev/null +++ b/docs/platforms/javascript/common/install/esm-without-import.mdx @@ -0,0 +1,54 @@ +--- +title: ESM without CLI Flag +sidebar_order: 11 +description: "Learn about running Sentry in an ESM application, without the --import flag." +supported: + - javascript.node + - javascript.connect + - javascript.express + - javascript.fastify + - javascript.koa +--- + + + Are you unsure if you should use this installation method? Review our + [installation methods](../). + + +When running your application in ESM mode, you will most likely want to follow the ESM instructions. 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. + + +This installation method has a fundamental restriction: It only supports limited performance instrumentation. Only basic `http` instrumentation will work, and no DB or framework-specific instrumentation will be available. + +Because of this, we recommend using this only if the `--import` flag is not an option for you. + + + +You need to create a file named `instrument.mjs` that imports and initializes Sentry: + + + +```javascript {tabTitle:ESM} {filename: instrument.mjs} +import * as Sentry from "@sentry/node"; + +// Ensure to call this before importing any other modules! +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + // Add Performance Monitoring by setting tracesSampleRate + // We recommend adjusting this value in production + tracesSampleRate: 1.0, +}); +``` + +You need to import the `instrument.mjs` file before importing any other modules in your application. This is necessary to ensure that Sentry can automatically instrument all modules in your application: + +```javascript {filename: app.mjs} +// Import this first! +import "./instrument"; + +// Now import other modules +import http from "http"; + +// Your application code goes here +``` diff --git a/docs/platforms/javascript/common/install/esm.mdx b/docs/platforms/javascript/common/install/esm.mdx index 0f3ff8cc86200..f62ff76037014 100644 --- a/docs/platforms/javascript/common/install/esm.mdx +++ b/docs/platforms/javascript/common/install/esm.mdx @@ -10,7 +10,27 @@ supported: - javascript.koa --- -When running your application in ESM mode, you can't use `require()` to load modules. Instead, you have to use the `--import` command line options to load a module before the application starts: + + Are you unsure if you should use this installation method? Review our + [installation methods](../). + + +When running your application in ESM mode, you can't use `require()` to load modules. Instead, you have to use the `--import` command line options to load a module before the application starts. + +You need to create a file named `instrument.mjs` that imports and initializes Sentry: + +```javascript {tabTitle:ESM} {filename: instrument.mjs} +import * as Sentry from "@sentry/node"; + +// Ensure to call this before importing any other modules! +Sentry.init({ + dsn: "___PUBLIC_DSN___", + + // Add Performance Monitoring by setting tracesSampleRate + // We recommend adjusting this value in production + tracesSampleRate: 1.0, +}); +``` Adjust the Node.js call for your application to use the [--import](https://nodejs.org/api/cli.html#--importmodule) parameter and point it at `instrument.js`, which contains your `Sentry.init()` code: @@ -20,10 +40,3 @@ node --import ./instrument.mjs app.mjs ``` We do not support ESM in Node versions before 18.19.0. - -## When to use this - -Most node applications today are either written in CommonJS (CJS), or compiled to CJS before running them. -CommonJS uses `require()` to load modules. Our recommended installation method when using CommonJS is to require the `instrument.js` file at the top of your application. However, if your application is run in ESM mode, this will not work. In this case, you can follow the docs on this page. - -Note that even if your application is written in ESM (using `import`), it may still be _run_ in CJS. For example, almost all applications written in TypeScript are compiled to CJS before running them. In this case, you should follow the [CommonJS instructions](../commonjs). diff --git a/docs/platforms/javascript/guides/fastify/index.mdx b/docs/platforms/javascript/guides/fastify/index.mdx index 4ef55161dfc9c..eeb5b837696b4 100644 --- a/docs/platforms/javascript/guides/fastify/index.mdx +++ b/docs/platforms/javascript/guides/fastify/index.mdx @@ -13,9 +13,7 @@ This guide explains how to setup Sentry in your Fastify application. Don't already have an account and Sentry project established? Head over to [sentry.io](https://sentry.io/signup/), then return to this page. - -This guide is for version 8.0.0 and up of `@sentry/node`. - +This guide is for version 8.0.0 and up of `@sentry/node`. ## Install