Add Gatsby docs for sentry config file (#4347)

Adds the docs supporting the Gatsby SDK initialization in a config file, see getsentry/sentry-javascript#4064.

Author: iker-barriocanal

src/includes/sourcemaps/upload/webpack/javascript.mdx

@@ -6,9 +6,11 @@ You can do this with the help of the our Webpack plugin, which internally uses o
 2. Confirm you have `project:write` selected under "Scopes"
 3. Install `@sentry/webpack-plugin` using `npm`
 4. Create `.sentryclirc` file with necessary configuration, as documented on this page
-5. Update your `webpack.config.js`
+5. Update your Webpack config
 
-```javascript
+<PlatformSection notSupported={["javascript.gatsby"]}>
+
+```javascript {filename:webpack.config.js}
 const SentryPlugin = require("@sentry/webpack-plugin");
 
 module.exports = {
@@ -22,6 +24,28 @@ module.exports = {
 };
 ```
 
+</PlatformSection>
+
+<PlatformSection supported={["javascript.gatsby"]}>
+
+```javascript {filename:gatsby-node.js}
+const SentryPlugin = require('@sentry/webpack-plugin');
+
+exports.onCreateWebpackConfig = ({ actions }) => {
+  actions.setWebpackConfig({
+    plugins: [
+      new SentryPlugin({
+        include: 'public',
+        ignore: ['app-*', 'polyfill-*', 'framework-*', 'webpack-runtime-*'],
+      }),
+    ],
+  });
+};
+```
+
+</PlatformSection>
+
+
 Learn more about further configuration of the plugin using our [Sentry Webpack Plugin documentation](https://github.com/getsentry/sentry-webpack-plugin).
 
 Additionally, you’ll need to configure the client to send the `release`:

src/platforms/javascript/guides/gatsby/index.mdx

@@ -24,47 +24,86 @@ yarn add @sentry/gatsby
 
 ## Connecting the SDK to Sentry
 
-Register the plugin in your Gatsby configuration file (typically `gatsby-config.js`).
+You can configure the SDK in one of two ways discussed below: by creating a configuration file, or defining the options along with the Gatsby configuration. If you define options in both places, the SDK will prioritize the `init` in the configuration file and ignore the options in the Gatsby configuration.
+
+### Sentry Configuration File
+
+<Note>
+
+The minimum version supporting the Sentry configuration file is `6.14.0`.
+
+</Note>
+
+Using a Sentry configuration file is the approach we recommend since it supports defining non-serializable options in the `init`. Note that you still need to include the plugin, even if you don't set any options.
 
 ```javascript {filename:gatsby-config.js}
 module.exports = {
-  // ...
   plugins: [
     {
       resolve: "@sentry/gatsby",
-      options: {
-        dsn: "___PUBLIC_DSN___",
-      },
     },
-    // ...
-  ],
+  ]
 };
 ```
 
-## Options
+Configure your `Sentry.init`:
+
+```javascript {filename:sentry.config.js}
+import * as Sentry from '@sentry/gatsby';
+
+Sentry.init({
+    dsn: "___PUBLIC_DSN___",
+    sampleRate: 1.0, // Adjust this value in production
+    beforeSend(event) {
+      // Modify the event here
+      if (event.user) {
+        // Don't send user's email address
+        delete event.user.email;
+      }
+      return event;
+    },
+    // ...
+});
+```
+
+```typescript {filename:sentry.config.ts}
+import * as Sentry from '@sentry/gatsby';
+
+Sentry.init({
+    dsn: "___PUBLIC_DSN___",
+    sampleRate: 1.0, // Adjust this value in production
+    beforeSend(event) {
+      // Modify the event here
+      if (event.user) {
+        // Don't send user's email address
+        delete event.user.email;
+      }
+      return event;
+    },
+    // ...
+});
+```
 
-The options field in the plugin configuration is passed directly to `Sentry.init`. Check our configuration docs for a [full list of the available options](configuration/options/).
+### Gatsby Plugin Configuration
 
-For example, the configuration below adjusts the `sampleRate` and `maxBreadcrumbs` options.
+Another alternative is to use Gatsby's [plugin configuration options](https://www.gatsbyjs.com/docs/how-to/plugins-and-themes/using-a-plugin-in-your-site/#using-plugin-configuration-options). While this keeps the SDK options with the plugin definition, it doesn't support non-serializable options.
 
 ```javascript {filename:gatsby-config.js}
 module.exports = {
-  // ...
-  plugins: [
     {
       resolve: "@sentry/gatsby",
       options: {
         dsn: "___PUBLIC_DSN___",
-        maxBreadcrumbs: 80,
-        sampleRate: 0.7,
+        sampleRate: 1.0, // Adjust this value in production
+        // Cannot set `beforeSend`
       },
     },
-    // ...
-  ],
+
+  ]
 };
 ```
 
-The Gatsby SDK will set certain options automatically based on environmental variables, but these can be overridden by setting custom options in the plugin configuration.
+With this approach, the SDK sets some options automatically based on environmental variables, but these can be overridden by setting custom options.
 
 `environment` (string)