Skip to content

docs(aws): Remove manual setup steps for ESM #14738

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
merged 2 commits into from
Aug 27, 2025
Merged

docs(aws): Remove manual setup steps for ESM #14738

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cf69563
docs(aws): Remove manual setup steps for ESM
msonnb Aug 27, 2025
cd966fe
remove potential confusion
msonnb Aug 27, 2025
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
79 changes: 8 additions & 71 deletions docs/platforms/javascript/guides/aws-lambda/install/layer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,24 +32,7 @@ Finally, set the region and copy the provided ARN value into the input.

## 2. Setup Options

Choose your setup method based on your Lambda function type:

<Alert level="info" title="ESM vs. CommonJS">

The setup instructions you should follow depend on how your function **runs** at runtime, not how it's written in your source code.

- **Use CommonJS instructions** if your function runs with CommonJS modules (uses `require()` and `module.exports` at runtime)
- **Use ESM instructions** if your function runs with ES modules (uses `import`/`export` at runtime)

**Important:** Even if you write your code with `import`/`export` syntax, your function might still run as CommonJS if you're using TypeScript or a build tool that compiles to CommonJS. Check your build output or Lambda runtime configuration to determine which applies to your function.

</Alert>

### Option A: Automatic Setup

**CommonJS functions** support fully automatic setup using environment variables - both SDK initialization and handler wrapping are handled automatically.

**ESM functions** support automatic SDK initialization via environment variables, but require manual handler wrapping.
### Option A: Automatic Setup (recommended)

In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/).

Expand All @@ -59,15 +42,7 @@ Select which Sentry features you'd like to install in addition to Error Monitori

Set the following environment variables in your Lambda function configuration:

```bash {tabTitle:CommonJS}
NODE_OPTIONS="--require @sentry/aws-serverless/awslambda-auto"
SENTRY_DSN="___PUBLIC_DSN___"
# ___PRODUCT_OPTION_START___ performance
SENTRY_TRACES_SAMPLE_RATE="1.0"
# ___PRODUCT_OPTION_END___ performance
```

```bash {tabTitle:ESM}
```bash
NODE_OPTIONS="--import @sentry/aws-serverless/awslambda-auto"
SENTRY_DSN="___PUBLIC_DSN___"
# ___PRODUCT_OPTION_START___ performance
Expand All @@ -79,29 +54,15 @@ To set environment variables, navigate to your Lambda function, select **Configu

![](./img/env_vars.png)

<Alert level="info" title="For ESM Lambda Functions">

You'll also need to manually wrap your handler as shown below:

```javascript {filename:index.mjs}
import * as Sentry from "@sentry/aws-serverless";

export const handler = Sentry.wrapHandler(async (event, context) => {
// Your handler code
});
```

</Alert>

### Option B: Manual Setup

Instead of using environment variables, you can manually initialize the SDK and wrap your handler in code. This approach works for both CommonJS and ESM functions and allows for further customization of the SDK setup.
To further customize the SDK setup, you can also manually initialize the SDK in your lambda function. The benefit of this installation method is that you can fully customize your Sentry SDK setup in a `Sentry.init` call.

Note that you don't have to actually install an NPM package for this to work, as the package is already included in the Lambda Layer.

#### For CommonJS Lambda Functions
Create a new file, for example `instrument.js` to initialize the SDK:

```javascript {filename:index.js}
```javascript {filename:instrument.js} {tabTitle:CommonJS}
const Sentry = require("@sentry/aws-serverless");

Sentry.init({
Expand All @@ -120,33 +81,9 @@ Sentry.init({
tracesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ performance
});

// Your package imports

exports.handler = Sentry.wrapHandler(async (event, context) => {
// Your handler code
});
```

It's important to add both, the `Sentry.init` call outside the handler function and the `Sentry.wrapHandler` wrapper around your function to automatically catch errors and performance data. Make sure that the `Sentry.init` call and the import statement are at the very top of your file before any other imports.

#### For ESM Lambda Functions

First, wrap your handler:

```javascript {filename:index.mjs}{1,3}
import * as Sentry from "@sentry/aws-serverless";

export const handler = Sentry.wrapHandler(async (event, context) => {
// Your handler code
});
```

Due to ESM limitations, you need to initialize the SDK in a separate file and load it before your function starts.

Create a new file, for example `instrument.mjs` to initialize the SDK:

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

Sentry.init({
Expand All @@ -169,10 +106,10 @@ Sentry.init({

##### Load the SDK

To load the SDK before your function starts, you need to preload the `instrument.mjs` by setting the `NODE_OPTIONS` environment variable:
To load the SDK before your function starts, you need to preload the `instrument.js` by setting the `NODE_OPTIONS` environment variable:

```bash
NODE_OPTIONS="--import ./instrument.mjs"
NODE_OPTIONS="--import ./instrument.js"
Copy link

Choose a reason for hiding this comment

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

Bug: Incorrect Node Options for CommonJS Modules

The documentation for both automatic and manual setup now instructs CommonJS Lambda functions to use NODE_OPTIONS="--import ...". However, --import is for ES modules; CommonJS functions need --require to load modules like awslambda-auto or instrument.js. This will cause runtime errors and prevent CommonJS functions from starting.

Additional Locations (3)

Fix in Cursor Fix in Web

```

That's it — make sure to re-deploy your function and you're all set!
85 changes: 10 additions & 75 deletions docs/platforms/javascript/guides/aws-lambda/install/npm.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,17 +17,6 @@ Before you begin, make sure you have the following:
- You have a Lambda function deployed in AWS.
- You're able to deploy dependencies (i.e. `node_modules`) alongside your function code to AWS Lambda.

<Alert level="info" title="ESM vs. CommonJS">

The setup instructions you should follow depend on how your Lambda function **runs** at runtime, not how it's written in your source code.

- **Use CommonJS instructions** if your function runs with CommonJS modules (uses `require()` and `module.exports` at runtime)
- **Use ESM instructions** if your function runs with ES modules (uses `import`/`export` at runtime)

**Important:** Even if you write your code with `import`/`export` syntax, your function might still run as CommonJS if you're using TypeScript or a build tool that compiles to CommonJS. Check your build output or Lambda runtime configuration to determine which applies to your function.

</Alert>

## 2. Install

In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). You can also collect and analyze performance profiles from real users with [profiling](/product/explore/profiling/).
Expand Down Expand Up @@ -74,25 +63,11 @@ pnpm add @sentry/aws-serverless @sentry/profiling-node

## 3. Setup Options

Choose your setup method based on your Lambda function type:

### Option A: Automatic Setup

**CommonJS functions** support fully automatic setup using environment variables - both SDK initialization and handler wrapping are handled automatically.

**ESM functions** support automatic SDK initialization via environment variables, but require manual handler wrapping.
### Option A: Automatic Setup (recommended)

Set the following environment variables in your Lambda function configuration:

```bash {tabTitle:CommonJS}
NODE_OPTIONS="--require @sentry/aws-serverless/awslambda-auto"
SENTRY_DSN="___PUBLIC_DSN___"
# ___PRODUCT_OPTION_START___ performance
SENTRY_TRACES_SAMPLE_RATE="1.0"
# ___PRODUCT_OPTION_END___ performance
```

```bash {tabTitle:ESM}
```bash
NODE_OPTIONS="--import @sentry/aws-serverless/awslambda-auto"
SENTRY_DSN="___PUBLIC_DSN___"
# ___PRODUCT_OPTION_START___ performance
Expand All @@ -104,36 +79,20 @@ To set environment variables, navigate to your Lambda function, select **Configu

![](./img/env_vars.png)

<Alert level="info" title="For ESM Lambda Functions">

You'll also need to manually wrap your handler as shown below:

```javascript {tabTitle:ESM} {filename:index.mjs}{1,3}
import * as Sentry from "@sentry/aws-serverless";

export const handler = Sentry.wrapHandler(async (event, context) => {
// Your handler code
});
```

</Alert>

That's it - make sure to re-deploy your function and you're all set!

### Option B: Manual Setup

To further customize the SDK setup, you can also manually initialize the SDK in your lambda function. The benefit of this installation method is that you can fully customize your Sentry SDK setup in a `Sentry.init` call.

#### For CommonJS Lambda Functions

You can initialize the SDK directly in your main handler file:
Create a new file, for example `instrument.js` to initialize the SDK:

```javascript {tabTitle:CommonJS} {filename:index.js}
```javascript {filename:instrument.js} {tabTitle:CommonJS}
const Sentry = require("@sentry/aws-serverless");
// ___PRODUCT_OPTION_START___ profiling
const { nodeProfilingIntegration } = require("@sentry/profiling-node");

// ___PRODUCT_OPTION_END___ profiling

Sentry.init({
dsn: "___PUBLIC_DSN___",

Expand All @@ -158,33 +117,9 @@ Sentry.init({
profilesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ profiling
});

// Your package imports

exports.handler = Sentry.wrapHandler(async (event, context) => {
// Your handler code
});
```

It's important to add both, the `Sentry.init` call outside the handler function and the `Sentry.wrapHandler` wrapper around your function to automatically catch errors and performance data. Make sure that the `Sentry.init` call and the import statement are at the very top of your file before any other imports.

#### For ESM Lambda Functions

First, wrap your handler:

```javascript {tabTitle:ESM} {filename:index.mjs}{1,3}
import * as Sentry from "@sentry/aws-serverless";

export const handler = Sentry.wrapHandler(async (event, context) => {
// Your handler code
});
```

Due to ESM limitations, you need to initialize the SDK in a separate file and load it before your function starts.

Create a new file, for example `instrument.mjs` to initialize the SDK:

```javascript {tabTitle:ESM} {filename:instrument.mjs}
```javascript {filename:instrument.mjs} {tabTitle:ESM}
import * as Sentry from "@sentry/aws-serverless";
// ___PRODUCT_OPTION_START___ profiling
import { nodeProfilingIntegration } from "@sentry/profiling-node";
Expand All @@ -198,9 +133,9 @@ Sentry.init({
sendDefaultPii: true,
// ___PRODUCT_OPTION_START___ profiling
integrations: [nodeProfilingIntegration()],

// ___PRODUCT_OPTION_END___ profiling
// ___PRODUCT_OPTION_START___ performance

// Add Tracing by setting tracesSampleRate and adding integration
// Set tracesSampleRate to 1.0 to capture 100% of transactions
// We recommend adjusting this value in production
Expand All @@ -218,10 +153,10 @@ Sentry.init({

##### Load the SDK

To load the SDK before your function starts, you need to set the `NODE_OPTIONS` environment variable:
To load the SDK before your function starts, you need to preload the `instrument.js` by setting the `NODE_OPTIONS` environment variable:

```bash {tabTitle:ESM}
NODE_OPTIONS="--import ./instrument.mjs"
```bash
NODE_OPTIONS="--import ./instrument.js"
```

To set environment variables, navigate to your Lambda function, select **Configuration**, then **Environment variables**.
Expand Down
Loading