Skip to content

docs(js): Update Gatsby quick start guide #16270

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
inventarSarah wants to merge 2 commits into
base: master
Choose a base branch
from
+109 −10
Open

docs(js): Update Gatsby quick start guide #16270

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
560a79d
draft gatsby quick start guide
inventarSarah Feb 5, 2026
a769db8
updated Gatsby quick start guide
inventarSarah Feb 5, 2026
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
119 changes: 109 additions & 10 deletions docs/platforms/javascript/guides/gatsby/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,19 @@
---
title: Gatsby
sdk: "sentry.javascript.gatsby"
description: "Learn how to use Sentry's Gatsby SDK."
description: "Learn how to set up Sentry in your Gatsby application, capture your first errors and traces, and view them in Sentry."
categories:
- javascript
- browser
---

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

To use Sentry with your Gatsby application, you will need to use `@sentry/gatsby` (Sentry's Gatsby SDK):
## Step 1: Install

### Install the Sentry SDK

Run the command for your preferred package manager to add the Sentry SDK to your application:

```bash {tabTitle:npm}
npm install @sentry/gatsby --save
Expand All @@ -25,13 +29,15 @@ pnpm add @sentry/gatsby

<Alert>

`@sentry/gatsby` is a wrapper around the `@sentry/react` package, with added functionality related to Gatsby. All methods available in the `@sentry/react` package can also be imported from `@sentry/gatsby`.
`@sentry/gatsby` is a wrapper around the `@sentry/react` package, with additional Gatsby-specific functionality. This means that you can import all methods available in the `@sentry/react` package from `@sentry/gatsby`.

</Alert>

Register the `@sentry/gatsby` plugin in your Gatsby configuration file (typically `gatsby-config.js`).
### Register the Sentry SDK

Register `@sentry/gatsby` in your Gatsby configuration file (typically `gatsby-config.(js|ts)`).

```javascript {filename:gatsby-config.js}
```javascript {tabTitle: CommonJS}{filename:gatsby-config.(js|ts)}
module.exports = {
plugins: [
{
Expand All @@ -41,11 +47,24 @@ module.exports = {
};
```

## Configure
```javascript {tabTitle: ESM}{filename:gatsby-config.(js|ts)}
import type { GatsbyConfig } from "gatsby";

const config: GatsbyConfig = {
plugins: [
// ...
{
resolve: "@sentry/gatsby"
},
],
};

export default config;
```

In addition to capturing errors, you can monitor interactions between multiple services or applications by [enabling tracing](/concepts/key-terms/tracing/). You can also get to the root of an error or performance issue faster, by watching a video-like reproduction of a user session with [session replay](/product/explore/session-replay/web/getting-started/).
## Step 2: Configure

Select which Sentry features you'd like to install in addition to Error Monitoring to get the corresponding installation and configuration instructions below.
Choose the features you want to configure, and this guide will show you how:

<OnboardingOptionButtons
options={[
Expand All @@ -57,7 +76,11 @@ Select which Sentry features you'd like to install in addition to Error Monitori
]}
/>

Then, configure your `Sentry.init`. For this, create a new file called `sentry.config.js` in the root of your project and add the following code:
<PlatformContent includePath="getting-started-features-expandable" />

### Initialize the Sentry SDK

Initialize Sentry as early as possible in your application. For this, create a new file `sentry.config.(js|ts)` in your project root and add the following:

```javascript {filename:sentry.config.(js|ts)}
import * as Sentry from "@sentry/gatsby";
Expand Down Expand Up @@ -108,3 +131,79 @@ Sentry.init({
// ___PRODUCT_OPTION_END___ session-replay
});
```

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

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

## Step 4: Avoid Ad Blockers With Tunneling (Optional)

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

## Step 6: Verify Your Setup

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

### Issues

To verify that Sentry captures errors and creates issues in your Sentry project, add the following test button to one of your pages:

```javascript {filename:index.(jsx|tsx)}
<button
type="button"
onClick={() => {
throw new Error("Sentry Test Error");
}}
>
Break the world
</button>
```

<OnboardingOption optionId="performance" hideForThisOption>
Open the page in a browser and click the button to trigger a frontend error.
</OnboardingOption>

<PlatformContent includePath="getting-started-browser-sandbox-warning" />

<OnboardingOption optionId="performance">
### Tracing
To test your tracing configuration, update the previous code snippet and wrap the error in a custom span:

```javascript {filename:index.(jsx|tsx)}
<button
type="button"
onClick={() => {
Sentry.startSpan({ op: "test", name: "Example Frontend Span" }, () => {
throw new Error("Sentry Test Error");
});
}}
>
Break the world
</button>
```

Open the page in a browser and click the button to trigger a frontend error and trace.

</OnboardingOption>

### View Captured Data in Sentry

Now, 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 Gatsby application and 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 backend using one of our [SDKs](/)
- Continue to <PlatformLink to="/configuration">customize your configuration</PlatformLink>
- Learn how to <PlatformLink to="/usage">manually capture errors</PlatformLink>

<Expandable permalink={false} title="Are you having problems setting up the SDK?">
- Find various topics in <PlatformLink to="/troubleshooting">Troubleshooting</PlatformLink>
- [Get support](https://sentry.zendesk.com/hc/en-us/)

</Expandable>