Skip to content

docs(js): Update Bun quick start guide #15419

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+103 −46
Open

docs(js): Update Bun quick start guide #15419

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
129 changes: 83 additions & 46 deletions docs/platforms/javascript/guides/bun/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
title: Bun
description: Learn how to manually set up Sentry in your Bun app and capture your first errors.
sdk: sentry.javascript.bun
categories:
- javascript
Expand All @@ -10,29 +11,30 @@ categories:

<PlatformContent includePath="getting-started-prerequisites" />

## Install
## Step 1: Install

In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/).
Choose the features you want to configure, and this guide will show you how:

Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below.
<OnboardingOptionButtons
options={["error-monitoring", "performance", "logs"]}
/>

<OnboardingOptionButtons options={["error-monitoring", "performance", "logs"]} />
<PlatformContent includePath="getting-started-features-expandable" />

Sentry captures data by using an SDK within your application's runtime.
### Install the SDK

Use the Bun package manager to add the Sentry SDK to your application:

```bash {tabTitle:Bun}
bun add @sentry/bun
```

## Configure

Configuration should happen as early as possible in your application's lifecycle.
## Step 2: Configure

Sentry should be initialized as early in your app as possible. It is essential that you call `Sentry.init` before you require any other modules in your application—otherwise, auto-instrumentation of these modules will _not_ work.
### Initialize the Sentry SDK

Once this is done, Sentry's Bun SDK captures unhandled exceptions as well as tracing data for your application.

You need to create a file named `instrument.js` that imports and initializes Sentry:
Sentry should be initialized as early in your app as possible.
To import and initialize Sentry, create a file named `instrument.js` in the root directory of your project and add the following code:

```javascript {filename: instrument.js}
import * as Sentry from "@sentry/bun";
Expand All @@ -53,22 +55,17 @@ Sentry.init({
// https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate
tracesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ performance
// ___PRODUCT_OPTION_START___ logs

// Enable logs to be sent to Sentry
enableLogs: true,
// ___PRODUCT_OPTION_END___ logs
});
```

Once you set a `tracesSampleRate`, performance instrumentation is automatically enabled for you. See <PlatformLink to="/tracing/instrumentation/automatic-instrumentation">Automatic Instrumentation</PlatformLink> to learn about all the things that the SDK automatically instruments for you.

You can also manually capture performance data - see <PlatformLink to="/tracing/instrumentation/custom-instrumentation">Custom Instrumentation</PlatformLink> for details.

<PlatformContent includePath="getting-started-sourcemaps" />

## Use
### Apply Instrumentation to Your App

<Alert level='warning'>

Import `instrument.js` before any other modules to ensure Sentry initializes early. If you initialize later, auto-instrumentation and modules like database monitoring, agent monitoring, tracing may not work.

</Alert>
Import `instrument.js` before any other modules to make sure Sentry initializes early. If you initialize later, auto-instrumentation and modules like tracing may not work.
Copy link
Member

@s1gr1d s1gr1d Nov 14, 2025

Choose a reason for hiding this comment

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

Bun has the same problem as Node with ESM (in Node, we have the "Installation methods"). In bun we would need to --preload this instrumentation file to be loaded before everything else: https://bun.com/docs/runtime#param-preload

This is out of scope for this PR but I just want to mention that. We need to improve our docs to be less Node-focused and also include other runtimes such as Bun and Deno in the future.


```javascript {filename: app.js}
// Import this first!
Expand All @@ -80,33 +77,73 @@ import http from "http";
// Your application code goes here
```

## Verify
## Step 3: Add Readable Stack Traces With Source Maps (Optional)

<PlatformContent includePath="getting-started-sourcemaps-short-version" />

## Step 4: Verify Your Setup

Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.

### Issues

This snippet includes an intentional error, so you can test that everything is working as soon as you set it up.
First, let's verify that Sentry captures errors and creates issues in your Sentry project. Add the following code snippet to your main application file, which will call an undefined function, triggering an error that Sentry will capture:

```javascript
// ___PRODUCT_OPTION_START___ performance
Sentry.startSpan({
op: "test",
name: "My First Test Transaction",
// ___PRODUCT_OPTION_END___ performance
}, () => {
setTimeout(() => {
try {
foo();
} catch (e) {
Sentry.captureException(e);
}
}, 99);
// ___PRODUCT_OPTION_START___ performance
});
// ___PRODUCT_OPTION_END___ performance
setTimeout(() => {
try {
foo();
} catch (e) {
Sentry.captureException(e);
}
}, 99);
```

<OnboardingOption optionId="performance">
### Tracing
To test your tracing configuration, update the previous code snippet by starting a trace to measure the time it takes for the execution of your code:

```javascript
Sentry.startSpan(
{
op: "test",
name: "My First Test Transaction",
},
() => {
setTimeout(() => {
try {
foo();
} catch (e) {
Sentry.captureException(e);
}
}, 99);
}
);
```

<Alert>
</OnboardingOption>

### View Captured Data in Sentry

Finally, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear).

<PlatformContent includePath="getting-started-verify-locate-data" />

## Next Steps

At this point, you should have integrated Sentry into your Bun application, which should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics.
Our next recommended steps for you are:

- Extend Sentry to your frontend using one of our [frontend SDKs](/)
Copy link
Contributor

@coolguyzone coolguyzone Nov 13, 2025

Choose a reason for hiding this comment

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

just double-checking, this is meant to go to the docs homepage?

- Learn how to <PlatformLink to="/usage">manually capture errors</PlatformLink>
- Continue to <PlatformLink to="/configuration">customize your configuration</PlatformLink>
- Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts

Learn more about manually capturing an error or message in our <PlatformLink to="/usage/">Usage documentation</PlatformLink>.
<Expandable permalink={false} title="Are you having problems setting up the SDK?">

</Alert>
- Find various topics in <PlatformLink to="/troubleshooting">Troubleshooting</PlatformLink>
- [Get support](https://sentry.zendesk.com/hc/en-us/)

To view and resolve the recorded error, log into [sentry.io](https://sentry.io) and select your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved.
</Expandable>
13 changes: 13 additions & 0 deletions platform-includes/getting-started-features-expandable/javascript.bun.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<Expandable title="Want to learn more about these features?">

- [**Issues**](/product/issues) (always enabled): Sentry's core error monitoring product that automatically reports errors,
uncaught exceptions, and unhandled rejections. If you have something that
looks like an exception, Sentry can capture it.
- [**Tracing**](/product/tracing): Track software performance while seeing the
impact of errors across multiple systems. For example, distributed tracing
allows you to follow a request from the frontend to the backend and back.
- [**Logs**](/product/explore/logs): Centralize and analyze your application logs to
correlate them with errors and performance issues. Search, filter, and
visualize log data to understand what's happening in your applications.

</Expandable>
7 changes: 7 additions & 0 deletions platform-includes/getting-started-verify-locate-data/javascript.bun.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
<Expandable title="Need help locating the captured errors in your Sentry project?">

1. Open the [**Issues**](https://sentry.io/issues) page and select an error from the issues list to view the full details and context of this error. For more details, see this [interactive walkthrough](/product/sentry-basics/integrate-frontend/generate-first-error/#ui-walkthrough).
2. Open the [**Traces**](https://sentry.io/explore/traces) page and select a trace to reveal more information about each span, its duration, and any errors. For an interactive UI walkthrough, click [here](/product/sentry-basics/distributed-tracing/generate-first-error/#ui-walkthrough).
3. Open the [**Logs**](https://sentry.io/explore/logs) page and filter by service, environment, or search keywords to view log entries from your application. For an interactive UI walkthrough, click [here](/product/explore/logs/#overview).

</Expandable>
Loading