feat(js): Add Documentation for Sentry Astro SDK

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