feat(js): Add Documentation for Sentry Astro SDK (#8267)

This change includes adjustments for Astro in the following pages:
* Getting Started shows the semi-automatic setup via the `astro` CLI
* Added "Manual Setup" page similarly, to SvelteKit, Remix and NextJS with all possible configuration options
* Adjusted source map docs to not display the full range of source maps upload material. The Astro SDK ships with the Vite plugin, so there shouldn't be too much need for other resources than troubleshooting. 
* Added Astro specific setup for Replay (This is the first SDK that actually enables Replay by default. However, there are two ways how users can manually customize or add Replay).
* Added various platform includes for performance monitoring snippets

---------

Co-authored-by: Shana Matthews <[email protected]>

Author: Lms24

src/components/orgAuthTokenNote.tsx

@@ -38,7 +38,7 @@ export function OrgAuthTokenNote() {
           <ExternalLink href={`https://sentry.io/auth/login/?next=${url}`}>
             sign in
           </ExternalLink>{' '}
-          to create a token directly from the docs.
+          to create a token directly from this page.
         </Note>
       </SignedInCheck>
 
@@ -48,7 +48,7 @@ export function OrgAuthTokenNote() {
           <ExternalLink href={orgAuthTokenUrl} target="_blank">
             manually create an Auth Token
           </ExternalLink>{' '}
-          or create a token directly from the docs. A created token will only be visible
+          or create a token directly from this page. A created token will only be visible
           once right after creation - make sure to copy it!
         </Alert>
       </SignedInCheck>

src/platform-includes/capture-error/javascript.astro.mdx

@@ -0,0 +1,11 @@
+You can pass an `Error` object to `captureException()` to have it captured as an event. It's also possible to pass non-`Error` objects and strings, but be aware that the resulting events in Sentry may be missing a stack trace.
+
+```javascript
+import * as Sentry from "@sentry/astro";
+
+try {
+  aFunctionThatMightFail();
+} catch (err) {
+  Sentry.captureException(err);
+}
+```

src/platform-includes/distributed-tracing/how-to-use/javascript.astro.mdx

@@ -0,0 +1,11 @@
+If you're using our Astro SDK, distributed tracing will work out of the box for the client and server runtimes.
+To get around possible [Browser CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) issues, you should define `tracePropagationTargets` on the client-side.
+
+```js
+// sentry.client.config.js
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [new BrowserTracing()],
+  tracePropagationTargets: ["https://myproject.org", /^\/api\//],
+});
+```

src/platform-includes/enriching-events/import/javascript.astro.mdx

@@ -0,0 +1,3 @@
+```javascript
+import * as Sentry from "@sentry/astro";
+```

src/platform-includes/getting-started-config/javascript.astro.mdx

@@ -0,0 +1,22 @@
+Get started by adding your DSN to your Astro config file:
+
+<SignInNote />
+
+```javascript {filename:astro.config.mjs}
+import { defineConfig } from "astro/config";
+import sentry from "@sentry/astro";
+
+export default defineConfig({
+  integrations: [
+    sentry({
+      dsn: "___PUBLIC_DSN___",
+      sourceMapsUploadOptions: {
+        project: "___PROJECT_SLUG___",
+        authToken: process.env.SENTRY_AUTH_TOKEN,
+      },
+    }),
+  ],
+});
+```
+
+Once you've added your `dsn`, the SDK will automatically capture and send errors and performance events to Sentry.

src/platform-includes/getting-started-install/javascript.astro.mdx

@@ -0,0 +1,9 @@
+We recommend installing the SDK by using the `astro` CLI:
+
+```bash
+npx astro add @sentry/astro
+```
+
+The `astro` CLI installs the SDK package and adds the Sentry integration to your `astro.config.mjs` file.
+
+To finish the setup, configure the Sentry integration.

src/platform-includes/getting-started-primer/javascript.astro.mdx

@@ -0,0 +1,14 @@
+Sentry's Astro SDK enables automatic reporting of errors and performance data.
+
+<Alert level="warning">
+
+The Astro SDK is in **Alpha** and may undergo **breaking changes**.
+Please report any issues you encounter in our [Github Repository](https://github.com/getsentry/sentry-javascript/issues/new/choose).
+
+</Alert>
+
+## Compatibility
+
+The minimum supported Astro version is `3.0.0`.
+This SDK currently only works on Node runtimes.
+Non-Node runtimes, like Vercel's Edge runtime or Cloudflare Pages, are currently not supported.

src/platform-includes/getting-started-sourcemaps/javascript.astro.mdx

@@ -0,0 +1,11 @@
+## Add Readable Stack Traces to Errors
+
+To get readable stack traces in your production builds, add the `SENTRY_AUTH_TOKEN` environment variable to your environment, like in a `.env` file or in your CI setup.
+
+<OrgAuthTokenNote />
+
+```bash {filename:.env}
+SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
+```
+
+This, in combination with your `sourceMapsUploadOptions` configuration, will <PlatformLink to="/sourcemaps">upload source maps</PlatformLink> to Sentry every time you make a production build.

src/platform-includes/getting-started-verify/javascript.astro.mdx

@@ -0,0 +1,13 @@
+Trigger a test error somewhere in your Astro app, for example in one of your pages:
+
+```html {filename: home.astro}
+<button onclick="throw new Error('This is a test error')">
+  Throw test error
+</button>
+```
+
+<Note>
+
+Errors triggered from within Browser DevTools are sandboxed and won't trigger an error handler. Place the snippet directly in your code instead.
+
+</Note>

src/platform-includes/performance/automatic-instrumentation-intro/javascript.astro.mdx

@@ -0,0 +1,2 @@
+The Sentry Astro SDK provides a `BrowserTracing` integration to add automatic instrumentation for monitoring the performance of browser applications, which is enabled by default.
+The SDK also automatically enables performance monitoring in your server-side code.

src/platform-includes/performance/configure-sample-rate/javascript.astro.mdx

@@ -0,0 +1,42 @@
+Either set `tracesSampleRate` in your `astro.config.mjs` file or in `sentry.(client|server).init.js`:
+
+<SignInNote />
+
+```javascript {tabTitle:Integration Config}{filename:astro.config.mjs}
+import { defineConfig } from "astro/config";
+import sentryAstro from "@sentry/astro";
+
+export default defineConfig({
+  integrations: [
+    sentryAstro({
+      dsn: "___PUBLIC_DSN___",
+      tracesSampleRate: 1.0,
+    }),
+  ],
+});
+```
+
+```javascript {tabTitle:Custom Config (client)} {filename:sentry.client.config.js}
+import * as Sentry from "@sentry/astro";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  tracesSampleRate: 1.0,
+});
+```
+
+```javascript {tabTitle:Custom Config (server)} {filename:sentry.server.config.js}
+import * as Sentry from "@sentry/astro";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  tracesSampleRate: 1.0,
+});
+```
+
+<Alert level="warning">
+
+The `tracesSampler` callback can only be specified in <PlatformLink to="/manual-setup/#manual-sdk-initialization">custom SDK init files</PlatformLink>.
+It is **not supported** in the `astro.config.mjs` file.
+
+</Alert>

src/platform-includes/performance/enable-automatic-instrumentation/javascript.astro.mdx

@@ -0,0 +1 @@
+To enable tracing, set either a `tracesSampleRate` or a `tracesSampler` in your SDK configuration options, as described in <PlatformLink to="/performance/">Set Up Performance</PlatformLink>.

src/platform-includes/performance/enable-tracing/javascript.astro.mdx

@@ -0,0 +1 @@
+The Sentry Astro SDK comes with performance monitoring included. To enable it, configure the sample rate as described below.

src/platform-includes/session-replay/install/javascript.astro.mdx

@@ -0,0 +1,11 @@
+The Replay integration is already included with the Sentry Astro SDK.
+
+```bash {tabTitle:npx}
+npx astro add @sentry/astro
+```
+
+<Note>
+
+If the Astro CLI setup doesn't work for you, you can also <PlatformLink to="/manual-setup/">set up the SDK manually</PlatformLink>.
+
+</Note>

src/platform-includes/session-replay/setup/javascript.astro.mdx

@@ -0,0 +1,53 @@
+Session replay is enabled by default if you use the SDK configuration in your `astro.config.mjs` file.
+
+You can customize Replay sample rates like so:
+
+```javascript {filename:astro.config.mjs}
+import { defineConfig } from "astro/config";
+import sentry from "@sentry/astro";
+
+export default defineConfig({
+  integrations: [
+    sentry({
+      dsn: "___PUBLIC_DSN___",
+      replaysSessionSampleRate: 0.2, // defaults to 0.1
+      replaysOnErrorSampleRate: 1.0, // defaults to 1.0
+    }),
+  ],
+});
+```
+
+If you have a <PlatformLink to="/manual-setup/#manual-sdk-initialization">custom SDK configuration file</PlatformLink> for the client side (`sentry.client.config.js`), add the Sentry `Replay` integration:
+
+```javascript {filename:sentry.client.config.js}
+import * as sentry from "@sentry/astro";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0,
+  integrations: [new Sentry.Replay()],
+});
+```
+
+<Alert level="warning">
+
+Do not add the `Replay` integration to your server-side Sentry config file (`sentry.server.config.js`).
+Session Replay can only be included on the client side.
+
+</Alert>
+
+### Lazy-loading Replay
+
+Once you've added the integration, Replay will start automatically. If you don't want to start it immediately (lazy-load it), you can use `addIntegration`:
+
+```javascript
+Sentry.init({
+  // Note, Replay is NOT instantiated below:
+  integrations: [],
+});
+
+// Sometime later
+const { Replay } = await import("@sentry/astro");
+Sentry.addIntegration(new Replay());
+```

src/platform-includes/sourcemaps/overview/javascript.astro.mdx

@@ -0,0 +1,85 @@
+## Configure Source Maps Upload
+
+Source maps upload should work if you followed the [Astro CLI installation guide](/platforms/javascript/guides/astro/#add-readable-stack-traces-to-errors). However, there are some options to configure source maps upload for your production builds for other configurations.
+
+### Enable Source Maps Upload
+
+To automatically upload source maps during production builds, add the `SENTRY_AUTH_TOKEN` environment variable to your environment, for example in a `.env` file or in your CI setup.
+
+<OrgAuthTokenNote />
+
+```bash {filename:.env}
+SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
+```
+
+Next, add your project slug to the `sourceMapsUploadOptions` in your Astro config:
+
+```javascript {filename:astro.config.mjs}
+export default defineConfig({
+  integrations: [
+    sentryAstro({
+      // Other Sentry options
+      sourceMapsUploadOptions: {
+        project: "___PROJECT_SLUG___",
+        authToken: process.env.SENTRY_AUTH_TOKEN,
+      },
+    }),
+  ],
+});
+```
+
+### Working With Old Authentication Tokens
+
+Source maps work best with [organization-scoped auth tokens](/product/accounts/auth-tokens/#organization-auth-tokens). If you are using an old self-hosted Sentry version that doesn't yet support org-based tokens or you're using a different type of Sentry auth token, you'll need to additionally specify your `org` slug in your `sourceMapsUploadOptions`:
+
+```javascript {filename:astro.config.mjs}
+export default defineConfig({
+  integrations: [
+    sentryAstro({
+      // Other Sentry options
+      sourceMapsUploadOptions: {
+        project: "___PROJECT_SLUG___",
+        org: "___ORG_SLUG___",
+        authToken: process.env.SENTRY_AUTH_TOKEN,
+      },
+    }),
+  ],
+});
+```
+
+### Disable Source Maps Upload
+
+You can disable automatic source maps upload in your Astro config:
+
+```javascript {filename:astro.config.mjs}
+export default defineConfig({
+  integrations: [
+    sentryAstro({
+      // Other Sentry options
+      sourceMapsUploadOptions: {
+        enabled: false,
+      },
+    }),
+  ],
+});
+```
+
+### Disabeling Telemetry Data Collection
+
+The Astro SDK uses the Sentry Vite plugin to upload source maps.
+This plugin collects telemetry data to help us improve the source map uploading experience.
+Read more about this in our [Vite plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin#telemetry).
+You can disable telemetry collection by setting `telemetry` to `false`:
+
+```javascript {filename:astro.config.mjs}
+export default defineConfig({
+  integrations: [
+    sentryAstro({
+      // Other Sentry options
+      sourceMapsUploadOptions: {
+        telemetry: false,
+      },
+    }),
+  ],
+});
+```

src/platform-includes/sourcemaps/primer/javascript.astro.mdx

@@ -0,0 +1,5 @@
+The Sentry Astro SDK will generate and upload source maps automatically during a production build, so that errors in Sentry contain readable stack traces.
+
+![Readable Stack Traces](/readable-stacktraces.png)
+
+The Astro SDK uses the [Sentry Vite Plugin](https://www.npmjs.com/package/@sentry/vite-plugin/) to upload source maps. See the <PlatformLink to="/manual-setup/#configure-source-maps-upload">Manual Configuration</PlatformLink> page and the Sentry [Vite plugin documentation](https://www.npmjs.com/package/@sentry/vite-plugin/#configuration) for more details.

src/platforms/common/index.mdx

@@ -22,7 +22,7 @@ Sentry captures data by using an SDK within your application’s runtime.
 
 ## Configure
 
-<PlatformSection notSupported={["android", "unity", "unreal", "javascript.nextjs", "apple.ios"]}>
+<PlatformSection notSupported={["android", "unity", "unreal", "javascript.nextjs", "javascript.astro", "apple.ios"]}>
 
 Configuration should happen as early as possible in your application's lifecycle.
 

src/platforms/javascript/common/install/index.mdx

@@ -4,6 +4,7 @@ sidebar_order: 1
 description: "Review our alternate installation methods."
 notSupported:
   - javascript.angular
+  - javascript.astro
   - javascript.bun
   - javascript.capacitor
   - javascript.cordova

src/platforms/javascript/common/sourcemaps/uploading/index.mdx

@@ -6,6 +6,7 @@ notSupported:
   - javascript.nextjs
   - javascript.remix
   - javascript.sveltekit
+  - javascript.astro
 ---
 
 <PlatformContent includePath="sourcemaps/upload/primer" />

src/platforms/javascript/guides/astro/config.yml

@@ -0,0 +1,8 @@
+title: Astro
+sdk: sentry.javascript.astro
+fallbackPlatform: javascript
+caseStyle: camelCase
+supportLevel: production
+categories:
+  - browser
+  - server