diff --git a/docs/platforms/javascript/guides/gatsby/index.mdx b/docs/platforms/javascript/guides/gatsby/index.mdx
index 5197cf2caeb6f..9f89caca16793 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 additional Gatsby-specific functionality. 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/)
+
+