From 560a79da0f3b3225dfe4671077c99b38ad4a4ad8 Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Thu, 5 Feb 2026 08:57:06 +0100 Subject: [PATCH 1/2] draft gatsby quick start guide --- .../javascript/guides/gatsby/index.mdx | 119 ++++++++++++++++-- 1 file changed, 109 insertions(+), 10 deletions(-) diff --git a/docs/platforms/javascript/guides/gatsby/index.mdx b/docs/platforms/javascript/guides/gatsby/index.mdx index 5197cf2caeb6f..d38526b384dfe 100644 --- a/docs/platforms/javascript/guides/gatsby/index.mdx +++ b/docs/platforms/javascript/guides/gatsby/index.mdx @@ -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 + -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 @@ -25,13 +29,15 @@ pnpm add @sentry/gatsby -`@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 added functionality related to Gatsby. This means, that you can import all methods available in the `@sentry/react` package from `@sentry/gatsby`. -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: [ { @@ -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: -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: + + +### 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"; @@ -108,3 +131,79 @@ Sentry.init({ // ___PRODUCT_OPTION_END___ session-replay }); ``` + +## Step 3: Add Readable Stack Traces With Source Maps (Optional) + + + +## Step 4: Avoid Ad Blockers With Tunneling (Optional) + + + +## 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)} + +``` + + + Open the page in a browser and click the button to trigger a frontend error. + + + + + +### Tracing +To test your tracing configuration, update the previous code snippet and wrap the error in a custom span: + +```javascript {filename:index.(jsx|tsx)} + +``` + +Open the page in a browser and click the button to trigger a frontend error and trace. + + + +### 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). + + + +## 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 customize your configuration +- Learn how to manually capture errors + + +- Find various topics in Troubleshooting +- [Get support](https://sentry.zendesk.com/hc/en-us/) + + From a769db82dbe50adbefd4848493be2f91e4b57a54 Mon Sep 17 00:00:00 2001 From: Sarah Mischinger Date: Thu, 5 Feb 2026 09:57:13 +0100 Subject: [PATCH 2/2] updated Gatsby quick start guide --- docs/platforms/javascript/guides/gatsby/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/platforms/javascript/guides/gatsby/index.mdx b/docs/platforms/javascript/guides/gatsby/index.mdx index d38526b384dfe..9f89caca16793 100644 --- a/docs/platforms/javascript/guides/gatsby/index.mdx +++ b/docs/platforms/javascript/guides/gatsby/index.mdx @@ -29,7 +29,7 @@ pnpm add @sentry/gatsby -`@sentry/gatsby` is a wrapper around the `@sentry/react` package, with added functionality related to Gatsby. This means, that you can import all methods available in the `@sentry/react` package 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`.