From 6165d3a882dd3ac5f865f58537a56f430dc28e5f Mon Sep 17 00:00:00 2001
From: RulaKhaled <rola.abuhasna@sentry.io>
Date: Fri, 14 Aug 2026 11:26:13 +0200
Subject: [PATCH] docs(astro): Document build-time vs runtime setup in the SDK
 README

sentry() no longer accepts runtime options like dsn after #23270, but the
package README still showed the old pattern.
---
 packages/astro/README.md | 50 ++++++++++++++++++++++++++++++++++------
 1 file changed, 43 insertions(+), 7 deletions(-)

diff --git a/packages/astro/README.md b/packages/astro/README.md
index bb671c5ef4e6..c4994a685987 100644
--- a/packages/astro/README.md
+++ b/packages/astro/README.md
@@ -31,7 +31,11 @@ Install the Sentry Astro SDK with the `astro` CLI:
 npx astro add @sentry/astro
 ```
 
-Add your DSN and source maps upload configuration:
+### Build-time Configuration
+
+Register the Sentry integration in your `astro.config.mjs`. This is where you configure build-time options such as
+source maps upload (`org`, `project`, `authToken`). Runtime SDK options (`dsn`, `environment`, `tracesSampleRate`, Replay
+sample rates, and so on) belong in dedicated init files, not on `sentry()`.
 
 ```javascript
 import { defineConfig } from 'astro/config';
@@ -40,11 +44,9 @@ import sentry from '@sentry/astro';
 export default defineConfig({
   integrations: [
     sentry({
-      dsn: '__DSN__',
-      sourceMapsUploadOptions: {
-        project: 'your-sentry-project-slug',
-        authToken: process.env.SENTRY_AUTH_TOKEN,
-      },
+      org: 'your-org-slug',
+      project: 'your-sentry-project-slug',
+      authToken: process.env.SENTRY_AUTH_TOKEN,
     }),
   ],
 });
@@ -57,6 +59,41 @@ token and add it to your environment variables:
 SENTRY_AUTH_TOKEN="your-token"
 ```
 
+### Runtime SDK Configuration
+
+If you do not add `sentry.client.config.ts` or `sentry.server.config.ts`, Sentry still initializes with default options
+and reads the DSN from `PUBLIC_SENTRY_DSN`. Add those files at the project root when you want to customize client or
+server options, and pass them to `Sentry.init()`.
+
+Set `PUBLIC_SENTRY_DSN` in your environment (for example in `.env`):
+
+```bash
+PUBLIC_SENTRY_DSN="__DSN__"
+```
+
+```javascript
+// sentry.client.config.ts
+import * as Sentry from '@sentry/astro';
+
+Sentry.init({
+  dsn: '__DSN__',
+  tracesSampleRate: 1.0,
+  integrations: [Sentry.replayIntegration()],
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0,
+});
+```
+
+```javascript
+// sentry.server.config.ts
+import * as Sentry from '@sentry/astro';
+
+Sentry.init({
+  dsn: '__DSN__',
+  tracesSampleRate: 1.0,
+});
+```
+
 ### Server Instrumentation
 
 For Astro apps configured for (hybrid) Server Side Rendering (SSR), the Sentry integration will automatically add
@@ -79,7 +116,6 @@ import sentry from '@sentry/astro';
 export default defineConfig({
   integrations: [
     sentry({
-      dsn: '__DSN__',
       autoInstrumentation: {
         requestHandler: false,
       },