From 5094d170aaacf93b2afad77c0f70215d5e49d15f Mon Sep 17 00:00:00 2001
From: betegon <miguelbetegongarcia@gmail.com>
Date: Tue, 11 Nov 2025 20:44:38 +0100
Subject: [PATCH 01/12] add nextjs guide

---
 .../content/docs/docs/quickstart/nextjs.mdx   | 368 ++++++++++++++++++
 1 file changed, 368 insertions(+)
 create mode 100644 packages/website/src/content/docs/docs/quickstart/nextjs.mdx

diff --git a/packages/website/src/content/docs/docs/quickstart/nextjs.mdx b/packages/website/src/content/docs/docs/quickstart/nextjs.mdx
new file mode 100644
index 00000000..3669800a
--- /dev/null
+++ b/packages/website/src/content/docs/docs/quickstart/nextjs.mdx
@@ -0,0 +1,368 @@
+---
+title: Next.js
+description: Get Spotlight running with Next.js in minutes
+---
+
+import DownloadButton from '../../../../components/DownloadButton.astro';
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+This quickstart sets up everything you need to use Spotlight with your Next.js application - including the CLI, UI, and MCP server.
+
+## Step 1: Install Sentry SDKs
+
+To install the Sentry SDK for Next.js, run the following command within your project:
+
+```bash
+npx @sentry/wizard@latest -i nextjs
+```
+
+The wizard will guide you through the setup process. When prompted for configuration options:
+
+* **DSN**: You can use any placeholder value like `https://spotlight@local/0` (no real Sentry account needed)
+* **Enable Tracing**: Select yes
+* **Enable Session Replay**: no need to enable this
+* **Enable Logs**: Select yes
+
+
+After the wizard completes, you'll have three configuration files generated: one for the client (`sentry.client.config.ts`), one for Edge Runtime (`sentry.edge.config.ts`), and one for the server (`sentry.server.config.ts`). These files will look like, or be very similar to, the examples below.
+
+
+#### Client-Side Configuration
+
+Update `sentry.client.config.ts` (or `.js`):
+
+```typescript
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: "https://spotlight@local/0", // Placeholder DSN
+
+  // Enable Spotlight integration for browser
+  integrations: [
+    Sentry.spotlightBrowserIntegration(),
+  ],
+
+  // Capture 100% of transactions for local development
+  tracesSampleRate: 1.0,
+
+  // Enable comprehensive logging
+  enableLogs: true,
+
+  // Optional: Enable session replay
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0,
+});
+```
+
+#### Server-Side Configuration
+
+Update `sentry.server.config.ts` (or `.js`):
+
+```typescript
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: "https://spotlight@local/0", // Placeholder DSN
+
+  // Capture 100% of transactions for local development
+  tracesSampleRate: 1.0,
+
+  // Enable comprehensive logging
+  enableLogs: true,
+});
+```
+
+#### Edge Runtime Configuration
+
+If you're using Edge Runtime, update `sentry.edge.config.ts` (or `.js`):
+
+```typescript
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: "https://spotlight@local/0", // Placeholder DSN
+
+  // Capture 100% of transactions for local development
+  tracesSampleRate: 1.0,
+
+  // Enable comprehensive logging
+  enableLogs: true,
+});
+```
+
+## Step 2: Install and Run Spotlight
+
+Now that your Next.js app is instrumented, you can run Spotlight to capture and display events.
+
+### Choose Your Installation Method
+
+<Tabs>
+  <TabItem label="npx">
+    The quickest way to get started:
+
+    ```bash
+    npx @spotlightjs/spotlight
+    ```
+
+    This starts Spotlight on `http://localhost:8969` where you can access the web UI.
+  </TabItem>
+  <TabItem label="Desktop App">
+    Download the Spotlight desktop application:
+
+    <DownloadButton>Download for Mac</DownloadButton>
+
+    The desktop app includes the sidecar and provides an enhanced interface for viewing events.
+  </TabItem>
+  <TabItem label="Docker">
+    Run Spotlight in a container:
+
+    ```bash
+    docker run --rm -p 8969:8969 ghcr.io/getsentry/spotlight:latest
+    ```
+  </TabItem>
+  <TabItem label="CLI">
+    Install the Spotlight CLI globally:
+
+    ```bash
+    npm install -g @spotlightjs/spotlight
+    ```
+
+    Then run:
+
+    ```bash
+    spotlight
+    ```
+  </TabItem>
+</Tabs>
+
+### Enable Spotlight in Development Only
+
+To ensure Spotlight only runs during development, you can conditionally enable the integration:
+
+```typescript
+// sentry.client.config.ts
+import * as Sentry from "@sentry/nextjs";
+
+Sentry.init({
+  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN || "https://spotlight@local/0",
+  integrations: [
+    // Only include Spotlight integration in development
+    ...(process.env.NODE_ENV === 'development' 
+      ? [Sentry.spotlightBrowserIntegration()] 
+      : []),
+  ],
+  tracesSampleRate: process.env.NODE_ENV === 'development' ? 1.0 : 0.1,
+  enableLogs: true,
+});
+```
+
+Alternatively, use the `SENTRY_SPOTLIGHT` environment variable:
+
+```bash
+# In your .env.local file
+SENTRY_SPOTLIGHT=1
+```
+
+Then in your SDK configuration:
+
+```typescript
+Sentry.init({
+  dsn: "https://spotlight@local/0",
+  spotlight: process.env.SENTRY_SPOTLIGHT === '1',
+  // ... other options
+});
+```
+
+## Step 3: Verify Everything Works
+
+1. **Start Spotlight** (if not already running):
+   ```bash
+   npx @spotlightjs/spotlight
+   ```
+
+2. **Run your Next.js application**:
+   ```bash
+   npm run dev
+   # or
+   pnpm dev
+   # or
+   yarn dev
+   ```
+
+3. **Open the Spotlight UI** in your browser:
+   ```
+   http://localhost:8969
+   ```
+
+4. **Trigger a test error** in your application. Create a test page or button that throws an error:
+
+```typescript
+// app/test-spotlight/page.tsx (App Router)
+'use client';
+
+export default function TestSpotlight() {
+  const triggerError = () => {
+    throw new Error("Test error for Spotlight!");
+  };
+
+  return (
+    <div>
+      <h1>Test Spotlight</h1>
+      <button onClick={triggerError}>Trigger Error</button>
+    </div>
+  );
+}
+```
+
+Or for Pages Router:
+
+```typescript
+// pages/test-spotlight.tsx
+export default function TestSpotlight() {
+  const triggerError = () => {
+    throw new Error("Test error for Spotlight!");
+  };
+
+  return (
+    <div>
+      <h1>Test Spotlight</h1>
+      <button onClick={triggerError}>Trigger Error</button>
+    </div>
+  );
+}
+```
+
+5. **Check the Spotlight UI** - you should see:
+   - The error appearing in the Errors tab
+   - Associated traces in the Traces tab
+   - Console logs in the Logs tab
+
+## App Router vs Pages Router
+
+Both Next.js routing approaches work with Spotlight. The main difference is in error boundary setup:
+
+### App Router
+
+The Sentry wizard should create a `global-error.tsx` file for you. If not, create it in your `app` directory:
+
+```typescript
+// app/global-error.tsx
+'use client';
+
+import * as Sentry from "@sentry/nextjs";
+import NextError from "next/error";
+import { useEffect } from "react";
+
+export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
+  useEffect(() => {
+    Sentry.captureException(error);
+  }, [error]);
+
+  return (
+    <html>
+      <body>
+        <NextError statusCode={undefined as any} />
+      </body>
+    </html>
+  );
+}
+```
+
+### Pages Router
+
+The wizard should create a custom `_error.tsx` file. If not, create it:
+
+```typescript
+// pages/_error.tsx
+import * as Sentry from "@sentry/nextjs";
+import type { NextPage } from "next";
+import type { ErrorProps } from "next/error";
+import NextError from "next/error";
+
+const CustomErrorComponent: NextPage<ErrorProps> = (props) => {
+  return <NextError statusCode={props.statusCode} />;
+};
+
+CustomErrorComponent.getInitialProps = async (contextData) => {
+  await Sentry.captureUnderscoreErrorException(contextData);
+  return NextError.getInitialProps(contextData);
+};
+
+export default CustomErrorComponent;
+```
+
+## Troubleshooting
+
+### Events Not Appearing in Spotlight
+
+**Issue**: You don't see any events in the Spotlight UI.
+
+**Solutions**:
+- Verify Spotlight is running on `http://localhost:8969`
+- Check that `spotlightBrowserIntegration()` is added to your client config
+- Ensure your Next.js dev server is running
+- Check the browser console for any connection errors
+- Try refreshing both the Spotlight UI and your application
+
+### Port Conflicts
+
+**Issue**: Port 8969 is already in use.
+
+**Solutions**:
+- Stop other services using port 8969
+- Or configure Spotlight to use a different port:
+  ```bash
+  npx @spotlightjs/spotlight --port 3001
+  ```
+  
+  Then update your SDK config:
+  ```typescript
+  Sentry.init({
+    spotlight: "http://localhost:3001/stream",
+    // ... other options
+  });
+  ```
+
+### CORS Errors
+
+**Issue**: CORS errors when connecting to Spotlight.
+
+**Solutions**:
+- Spotlight sidecar should handle CORS automatically
+- If using a custom port or host, ensure it's properly configured
+- Check that you're accessing both your app and Spotlight via `localhost` (not mixing `localhost` and `127.0.0.1`)
+
+### Missing Server-Side Events
+
+**Issue**: Only seeing client-side events, no server-side errors or traces.
+
+**Solutions**:
+- Verify `sentry.server.config.ts` is properly configured
+- Ensure `instrumentation.ts` exists in your project root (created by the wizard)
+- Check that `tracesSampleRate: 1.0` is set in server config
+- Restart your Next.js dev server after configuration changes
+
+## Next Steps
+
+Now that Spotlight is running with your Next.js application, explore more features:
+
+### Desktop App
+Try the [Spotlight Desktop App](/docs/desktop-app/) for an enhanced UI experience with better performance and dedicated window management.
+
+### MCP Integration
+Connect Spotlight to AI coding assistants like Cursor and Claude with the [MCP Server](/docs/mcp/). Your AI assistant can analyze errors, traces, and logs to help you debug faster.
+
+### CLI Commands
+Explore [CLI commands](/docs/cli/) to:
+- Tail events in your terminal
+- Run your application with automatic instrumentation
+- Stream logs and traces to stdout
+
+### Production Monitoring
+While Spotlight is perfect for local development, consider using [Sentry](https://sentry.io) for production monitoring. Since you've already installed the SDK, you just need to:
+1. Create a free Sentry account
+2. Replace the placeholder DSN with your real project DSN
+3. Adjust sample rates for production (e.g., `tracesSampleRate: 0.1`)
+
+Your application will seamlessly send production telemetry to Sentry while keeping development data in Spotlight.
+

From b9246b02c077cc6816f631c39653400891fa281d Mon Sep 17 00:00:00 2001
From: betegon <miguelbetegongarcia@gmail.com>
Date: Tue, 11 Nov 2025 22:01:29 +0100
Subject: [PATCH 02/12] add environment variable text

---
 .../content/docs/docs/quickstart/nextjs.mdx   | 56 ++++++++-----------
 1 file changed, 22 insertions(+), 34 deletions(-)

diff --git a/packages/website/src/content/docs/docs/quickstart/nextjs.mdx b/packages/website/src/content/docs/docs/quickstart/nextjs.mdx
index 3669800a..ce7e6463 100644
--- a/packages/website/src/content/docs/docs/quickstart/nextjs.mdx
+++ b/packages/website/src/content/docs/docs/quickstart/nextjs.mdx
@@ -106,20 +106,6 @@ Now that your Next.js app is instrumented, you can run Spotlight to capture and
 
     This starts Spotlight on `http://localhost:8969` where you can access the web UI.
   </TabItem>
-  <TabItem label="Desktop App">
-    Download the Spotlight desktop application:
-
-    <DownloadButton>Download for Mac</DownloadButton>
-
-    The desktop app includes the sidecar and provides an enhanced interface for viewing events.
-  </TabItem>
-  <TabItem label="Docker">
-    Run Spotlight in a container:
-
-    ```bash
-    docker run --rm -p 8969:8969 ghcr.io/getsentry/spotlight:latest
-    ```
-  </TabItem>
   <TabItem label="CLI">
     Install the Spotlight CLI globally:
 
@@ -132,35 +118,37 @@ Now that your Next.js app is instrumented, you can run Spotlight to capture and
     ```bash
     spotlight
     ```
+
+    This starts Spotlight on `http://localhost:8969` where you can access the web UI.
   </TabItem>
-</Tabs>
+  <TabItem label="Desktop App">
+    Download the Spotlight desktop application:
 
-### Enable Spotlight in Development Only
+    <DownloadButton>Download for Mac</DownloadButton>
 
-To ensure Spotlight only runs during development, you can conditionally enable the integration:
+    The desktop app includes the sidecar and provides an enhanced interface for viewing events.
+  </TabItem>
+  <TabItem label="Docker">
+    Run Spotlight in a container:
 
-```typescript
-// sentry.client.config.ts
-import * as Sentry from "@sentry/nextjs";
+    ```bash
+    docker run --rm -p 8969:8969 ghcr.io/getsentry/spotlight:latest
+    ```
+  </TabItem>
+</Tabs>
 
-Sentry.init({
-  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN || "https://spotlight@local/0",
-  integrations: [
-    // Only include Spotlight integration in development
-    ...(process.env.NODE_ENV === 'development' 
-      ? [Sentry.spotlightBrowserIntegration()] 
-      : []),
-  ],
-  tracesSampleRate: process.env.NODE_ENV === 'development' ? 1.0 : 0.1,
-  enableLogs: true,
-});
-```
+### Add environment variable to enable Spotlight
+
+:::note[When you don't need this]
+If you are using `spotlight run` to start Spotlight, you don't need to add this environment variable as we take care of it for you.
+:::
 
-Alternatively, use the `SENTRY_SPOTLIGHT` environment variable:
+ use the `SENTRY_SPOTLIGHT` environment variable:
 
 ```bash
 # In your .env.local file
-SENTRY_SPOTLIGHT=1
+NEXT_PUBLIC_SENTRY_SPOTLIGHT=1 # for frontend event sending
+SENTRY_SPOTLIGHT=1 # for backend event sending
 ```
 
 Then in your SDK configuration:

From dab8b49bd6b6330f10efc0edfe8d04eb5deb35cc Mon Sep 17 00:00:00 2001
From: betegon <miguelbetegongarcia@gmail.com>
Date: Wed, 12 Nov 2025 10:29:40 +0100
Subject: [PATCH 03/12] fix sidebar order

---
 packages/website/astro.config.mjs | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/packages/website/astro.config.mjs b/packages/website/astro.config.mjs
index 0a398e6c..c1de311f 100644
--- a/packages/website/astro.config.mjs
+++ b/packages/website/astro.config.mjs
@@ -75,17 +75,10 @@ export default defineConfig({
       ],
       sidebar: [
         {
-          label: "About",
-          items: [
-            {
-              label: "What is Spotlight?",
-              link: "/docs/about/",
-            },
-            {
-              label: "Architecture",
-              link: "/docs/architecture/",
-            },
-          ],
+          label: "Quick Starts",
+          autogenerate: {
+            directory: "docs/quickstart",
+          },
         },
         {
           label: "CLI",
@@ -117,6 +110,19 @@ export default defineConfig({
             directory: "docs/contribute",
           },
         },
+        {
+          label: "About",
+          items: [
+            {
+              label: "What is Spotlight?",
+              link: "/docs/about/",
+            },
+            {
+              label: "Architecture",
+              link: "/docs/architecture/",
+            },
+          ],
+        },
         {
           label: "Reference",
           autogenerate: {

From 1b2da61d0a5c5a936cd96a40fa06fc591ab7eef0 Mon Sep 17 00:00:00 2001
From: betegon <miguelbetegongarcia@gmail.com>
Date: Wed, 12 Nov 2025 10:59:26 +0100
Subject: [PATCH 04/12] add getting started page

---
 .../docs/docs/getting-started/index.mdx       | 158 ++++++++++++++++++
 1 file changed, 158 insertions(+)
 create mode 100644 packages/website/src/content/docs/docs/getting-started/index.mdx

diff --git a/packages/website/src/content/docs/docs/getting-started/index.mdx b/packages/website/src/content/docs/docs/getting-started/index.mdx
new file mode 100644
index 00000000..fbfa72ba
--- /dev/null
+++ b/packages/website/src/content/docs/docs/getting-started/index.mdx
@@ -0,0 +1,158 @@
+---
+title: Getting Started with Spotlight
+description: Install and configure Spotlight for local debugging with Sentry SDKs
+sidebar:
+  order: 0
+---
+
+import DownloadButton from '../../../../components/DownloadButton.astro';
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+:::note[You don't need a Sentry account to use Spotlight]
+:::
+
+Spotlight brings the power of Sentry into your local development environment. This guide will help you set up everything you need to start debugging with Spotlight.
+
+## Step 1: Install Sentry SDK
+
+Follow your language or framework setup to install Sentry's SDK here: [https://docs.sentry.io/](https://docs.sentry.io/). Follow Sentry docs and enable logs and set tracing sample rate to 1.
+
+**Come back here after you've installed the Sentry SDK.**
+
+## Step 2: Install Spotlight
+
+Choose the method that works best for your workflow:
+
+<Tabs>
+  <TabItem label="Quick Start (npx)">
+    The fastest way to get started:
+
+    ```bash
+    npx @spotlightjs/spotlight
+    ```
+
+    This starts Spotlight on `http://localhost:8969` where you can access the web UI.
+  </TabItem>
+  <TabItem label="Desktop App">
+    Download the Spotlight desktop application for the best experience:
+
+    <DownloadButton>Download for Mac</DownloadButton>
+
+    The desktop app includes:
+    - Dedicated window for debugging
+    - System tray integration
+    - Automatic updates
+    - Better performance
+  </TabItem>
+  <TabItem label="CLI (Global Install)">
+    Install the Spotlight CLI globally:
+
+    ```bash
+    npm install -g @spotlightjs/spotlight
+    ```
+
+    Then run:
+
+    ```bash
+    spotlight
+    ```
+
+    The CLI provides additional commands for streaming events and running applications.
+  </TabItem>
+  <TabItem label="Docker">
+    Run Spotlight in a container:
+
+    ```bash
+    docker run --rm -p 8969:8969 ghcr.io/getsentry/spotlight:latest
+    ```
+  </TabItem>
+</Tabs>
+
+## Step 3: Configure Your SDK
+
+Now configure your Sentry SDK to send data to Spotlight. The exact configuration depends on your framework, but here's the pattern:
+
+### Frontend Applications
+
+For browser-based applications, enable the Spotlight browser integration:
+
+```javascript
+import * as Sentry from "@sentry/browser";
+
+Sentry.init({
+  dsn: "https://spotlight@local/0", // Placeholder DSN
+  
+  // Enable Spotlight integration
+  integrations: [
+    Sentry.spotlightBrowserIntegration(),
+  ],
+  
+  // Capture 100% of transactions locally
+  tracesSampleRate: 1.0,
+  
+  // Enable comprehensive logging
+  integrations: [
+    Sentry.captureConsoleIntegration({
+      levels: ['log', 'info', 'warn', 'error', 'debug'],
+    }),
+  ],
+});
+```
+
+### Backend Applications
+
+For Node.js and other backend applications:
+
+```javascript
+import * as Sentry from "@sentry/node";
+
+Sentry.init({
+  dsn: "https://spotlight@local/0", // Placeholder DSN
+
+  // Capture 100% of transactions locally
+  tracesSampleRate: 1.0,
+});
+```
+
+### Environment Variable
+
+:::note[When you don't need this]
+If you are using `spotlight run` to start Spotlight, you don't need to add this environment variable as we take care of it for you.
+:::
+
+You need to set the `SENTRY_SPOTLIGHT` environment variable to `1` to enable Spotlight if you're using `spotlight tail`, our UI or the MCP server.
+
+```bash
+# In your .env.local or .env file
+SENTRY_SPOTLIGHT=1
+```
+
+## Step 4: Verify Your Setup
+
+1. **Ensure Spotlight is running** (you should see the UI at http://localhost:8969)
+
+2. **Start your application** in development mode
+
+3. **Create a test error** to verify everything works:
+
+   ```javascript
+   // Add this temporary code to trigger a test error
+   setTimeout(() => {
+     throw new Error("Test error for Spotlight!");
+   }, 1000);
+   ```
+
+4. **Check the Spotlight UI** - you should see:
+   - The error in the Errors tab
+   - A trace showing the error context
+   - Console logs in the Logs tab
+
+🎉 **Success!** You're now capturing local telemetry with Spotlight.
+
+## Next Steps
+
+Now that Spotlight is running, explore its powerful features:
+
+- [CLI](/docs/cli/) - Run apps with automatic instrumentation, stream events, and tail logs in real-time
+- [MCP Server](/docs/mcp/) - Connect Spotlight to AI assistants like Cursor and Claude for AI-powered debugging assistance
+- [Desktop App](/docs/desktop-app/) - Enhanced debugging experience with dedicated window, system integration, and better performance

From 8560f2e775445b50cd32119fa967e76236465387 Mon Sep 17 00:00:00 2001
From: betegon <miguelbetegongarcia@gmail.com>
Date: Wed, 12 Nov 2025 10:59:37 +0100
Subject: [PATCH 05/12] redirect to getting started

---
 packages/website/src/content/docs/docs/index.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/website/src/content/docs/docs/index.mdx b/packages/website/src/content/docs/docs/index.mdx
index 5ff5ed1e..2195a903 100644
--- a/packages/website/src/content/docs/docs/index.mdx
+++ b/packages/website/src/content/docs/docs/index.mdx
@@ -10,11 +10,11 @@ hero:
     Debug faster with real-time error tracking, traces, and logs—right where you code.
   actions:
     - text: Get Started
-      link: /docs/about/
+      link: /docs/getting-started/
       variant: primary
     - text: View on GitHub
       link: https://github.com/getsentry/spotlight
       variant: secondary
 ---
 
-Welcome to the Spotlight documentation! Explore our guides and references to get the most out of your local debugging experience.
\ No newline at end of file
+Welcome to the Spotlight documentation! Explore our guides and references to get the most out of your local debugging experience.

From 33baf2522ea505da8003dce6c2e8bf58a6c4ca15 Mon Sep 17 00:00:00 2001
From: betegon <miguelbetegongarcia@gmail.com>
Date: Wed, 12 Nov 2025 10:59:47 +0100
Subject: [PATCH 06/12] add getting started to sidebar

---
 packages/website/astro.config.mjs | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/website/astro.config.mjs b/packages/website/astro.config.mjs
index c1de311f..61dba223 100644
--- a/packages/website/astro.config.mjs
+++ b/packages/website/astro.config.mjs
@@ -74,6 +74,10 @@ export default defineConfig({
         },
       ],
       sidebar: [
+        {
+          label: "Getting Started",
+          link: "/docs/getting-started/",
+        },
         {
           label: "Quick Starts",
           autogenerate: {

From 7a72226e97ef12d5bc37fc474e912f0623cd59a7 Mon Sep 17 00:00:00 2001
From: betegon <miguelbetegongarcia@gmail.com>
Date: Wed, 12 Nov 2025 10:59:59 +0100
Subject: [PATCH 07/12] link to getting started

---
 packages/website/src/content/docs/docs/desktop-app/index.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/website/src/content/docs/docs/desktop-app/index.mdx b/packages/website/src/content/docs/docs/desktop-app/index.mdx
index 1fc30c13..7c00ddbd 100644
--- a/packages/website/src/content/docs/docs/desktop-app/index.mdx
+++ b/packages/website/src/content/docs/docs/desktop-app/index.mdx
@@ -329,7 +329,7 @@ Spotlight is designed exclusively for development:
 
 ## Next Steps
 
-- [Configure your SDK](/docs/setup/) - Setup guide for different frameworks
+- [Configure your SDK](/docs/getting-started/) - Setup guide for different frameworks
 - [Use the CLI](/docs/cli/) - Terminal-based workflows
 - [MCP Integration](/docs/mcp/) - Connect to AI assistants
 - [Explore integrations](/docs/reference/integration/) - Custom integrations

From 128c1aeae3e22d2cbe0c437c3056c51714320d95 Mon Sep 17 00:00:00 2001
From: betegon <miguelbetegongarcia@gmail.com>
Date: Wed, 12 Nov 2025 11:00:06 +0100
Subject: [PATCH 08/12] improve nextjs guide

---
 .../content/docs/docs/quickstart/nextjs.mdx   | 27 ++--------
 .../src/content/docs/docs/setup/index.mdx     | 52 -------------------
 2 files changed, 4 insertions(+), 75 deletions(-)
 delete mode 100644 packages/website/src/content/docs/docs/setup/index.mdx

diff --git a/packages/website/src/content/docs/docs/quickstart/nextjs.mdx b/packages/website/src/content/docs/docs/quickstart/nextjs.mdx
index ce7e6463..3b42bddd 100644
--- a/packages/website/src/content/docs/docs/quickstart/nextjs.mdx
+++ b/packages/website/src/content/docs/docs/quickstart/nextjs.mdx
@@ -311,15 +311,6 @@ export default CustomErrorComponent;
   });
   ```
 
-### CORS Errors
-
-**Issue**: CORS errors when connecting to Spotlight.
-
-**Solutions**:
-- Spotlight sidecar should handle CORS automatically
-- If using a custom port or host, ensure it's properly configured
-- Check that you're accessing both your app and Spotlight via `localhost` (not mixing `localhost` and `127.0.0.1`)
-
 ### Missing Server-Side Events
 
 **Issue**: Only seeing client-side events, no server-side errors or traces.
@@ -332,25 +323,15 @@ export default CustomErrorComponent;
 
 ## Next Steps
 
-Now that Spotlight is running with your Next.js application, explore more features:
+Now that Spotlight is running with your Next.js application, explore its powerful features:
 
-### Desktop App
-Try the [Spotlight Desktop App](/docs/desktop-app/) for an enhanced UI experience with better performance and dedicated window management.
-
-### MCP Integration
-Connect Spotlight to AI coding assistants like Cursor and Claude with the [MCP Server](/docs/mcp/). Your AI assistant can analyze errors, traces, and logs to help you debug faster.
-
-### CLI Commands
-Explore [CLI commands](/docs/cli/) to:
-- Tail events in your terminal
-- Run your application with automatic instrumentation
-- Stream logs and traces to stdout
+- [CLI](/docs/cli/) - Run apps with automatic instrumentation, stream events, and tail logs in real-time
+- [MCP Server](/docs/mcp/) - Connect Spotlight to AI assistants like Cursor and Claude for AI-powered debugging assistance
+- [Desktop App](/docs/desktop-app/) - Enhanced debugging experience with dedicated window, system integration, and better performance
 
 ### Production Monitoring
 While Spotlight is perfect for local development, consider using [Sentry](https://sentry.io) for production monitoring. Since you've already installed the SDK, you just need to:
 1. Create a free Sentry account
 2. Replace the placeholder DSN with your real project DSN
-3. Adjust sample rates for production (e.g., `tracesSampleRate: 0.1`)
 
 Your application will seamlessly send production telemetry to Sentry while keeping development data in Spotlight.
-
diff --git a/packages/website/src/content/docs/docs/setup/index.mdx b/packages/website/src/content/docs/docs/setup/index.mdx
deleted file mode 100644
index 74a5494d..00000000
--- a/packages/website/src/content/docs/docs/setup/index.mdx
+++ /dev/null
@@ -1,52 +0,0 @@
----
-title: Using Spotlight
-description: Use Spotlight as a standalone application
----
-import DownloadButton from '../../../../components/DownloadButton.astro';
-import { Tabs, TabItem } from '@astrojs/starlight/components';
-
-Spotlight provides an Electron app that can be used to run the Sidecar as well as a dedicated instance of the overlay.
-
-## Installation
-
-Get started by downloading the latest version of the Electron app for your platform.
-
-<DownloadButton>Download for Mac</DownloadButton>
-
-### Other ways
-
-If Electron apps are not your thing or you are not using a Mac we have some more ways to run Spotlight with it's web UI:
-
-<Tabs>
-  <TabItem label="npx">
-  ```shell
-  npx @spotlightjs/spotlight
-  ```
-  </TabItem>
-  <TabItem label="docker">
-  ```shell
-  docker run --rm -p 8969 ghcr.io/getsentry/spotlight:latest
-  ```
-  </TabItem>
-  <TabItem label="binary">
-  ```shell
-  curl -q https://spotlightjs.com/install.sh | sh
-  ```
-  </TabItem>
-</Tabs>
-
-## SDK Setup
-
-In addition to loading the application, make sure you've enabled spotlight in the relevant Sentry SDKs (e.g. via `spotlight: true`):
-
-For front-end applications, you need to enable the `spotlightBrowserIntegration` for it to work. This is to only include this bit of the code for the users of Spotlight:
-
-```javascript
-import * as Sentry from '@sentry/browser';
-
-Sentry.init({
-  dsn: '___DSN___',
-  integrations: [Sentry.spotlightBrowserIntegration()],
-  // ...other Sentry options
-});
-```

From 886a1b0dc70911f49135affd0f21938a5b59f82f Mon Sep 17 00:00:00 2001
From: betegon <miguelbetegongarcia@gmail.com>
Date: Thu, 27 Nov 2025 21:04:37 +0100
Subject: [PATCH 09/12] link to getting started

---
 packages/website/src/components/homepage/Footer.astro | 2 +-
 packages/website/src/components/homepage/Header.astro | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/website/src/components/homepage/Footer.astro b/packages/website/src/components/homepage/Footer.astro
index bbc6e63b..227dedcd 100644
--- a/packages/website/src/components/homepage/Footer.astro
+++ b/packages/website/src/components/homepage/Footer.astro
@@ -25,7 +25,7 @@
       <div>
         <h3 class="font-semibold mb-4">Resources</h3>
         <div class="space-y-2 text-sm">
-          <div><a href="/docs/setup" class="text-[#a5a5a5] hover:text-white transition-colors">Documentation</a></div>
+          <div><a href="/docs/getting-started/" class="text-[#a5a5a5] hover:text-white transition-colors">Documentation</a></div>
           <div><a href="/docs/contribute/" class="text-[#a5a5a5] hover:text-white transition-colors">Contribute</a></div>
         </div>
       </div>
diff --git a/packages/website/src/components/homepage/Header.astro b/packages/website/src/components/homepage/Header.astro
index 6367ec7c..ab3ceafb 100644
--- a/packages/website/src/components/homepage/Header.astro
+++ b/packages/website/src/components/homepage/Header.astro
@@ -24,7 +24,7 @@
       Download
     </a>
     <a
-      href="/docs/setup/"
+      href="/docs/getting-started/"
       class="text-sm text-[#a5a5a5] hover:text-white transition-colors no-underline"
     >
       Docs

From c8e2e35a1a0e05b27c8b5e92b5243c37c4024077 Mon Sep 17 00:00:00 2001
From: betegon <miguelbetegongarcia@gmail.com>
Date: Fri, 28 Nov 2025 13:08:39 +0100
Subject: [PATCH 10/12] add spotlight flag

---
 packages/website/src/content/docs/docs/quickstart/nextjs.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/website/src/content/docs/docs/quickstart/nextjs.mdx b/packages/website/src/content/docs/docs/quickstart/nextjs.mdx
index 3b42bddd..b56df6cd 100644
--- a/packages/website/src/content/docs/docs/quickstart/nextjs.mdx
+++ b/packages/website/src/content/docs/docs/quickstart/nextjs.mdx
@@ -13,7 +13,7 @@ This quickstart sets up everything you need to use Spotlight with your Next.js a
 To install the Sentry SDK for Next.js, run the following command within your project:
 
 ```bash
-npx @sentry/wizard@latest -i nextjs
+npx @sentry/wizard@latest -i nextjs --spotlight
 ```
 
 The wizard will guide you through the setup process. When prompted for configuration options:

From ddd328f8854038dde5bcb17c723d779f745fbc16 Mon Sep 17 00:00:00 2001
From: betegon <miguelbetegongarcia@gmail.com>
Date: Fri, 26 Dec 2025 18:43:28 +0100
Subject: [PATCH 11/12] update link

---
 packages/website/src/content/docs/docs/architecture.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/website/src/content/docs/docs/architecture.mdx b/packages/website/src/content/docs/docs/architecture.mdx
index 69a9b22b..8ee5de35 100644
--- a/packages/website/src/content/docs/docs/architecture.mdx
+++ b/packages/website/src/content/docs/docs/architecture.mdx
@@ -42,6 +42,6 @@ A single sidecar can serve multiple clients simultaneously:
 ## Learn More
 
 <CardGrid>
-  <LinkCard title="Getting Started" href="/docs/setup/" description="Choose how to run Spotlight" />
+  <LinkCard title="Getting Started" href="/docs/getting-started/" description="Install and configure Spotlight" />
   <LinkCard title="Sidecar Details" href="/docs/sidecar/" description="Configuration and SDK integration" />
 </CardGrid>

From 8d6ba96170e6556351f1ea77f56f52f66782b934 Mon Sep 17 00:00:00 2001
From: betegon <miguelbetegongarcia@gmail.com>
Date: Fri, 26 Dec 2025 18:47:16 +0100
Subject: [PATCH 12/12] fix integrations

---
 .../content/docs/docs/getting-started/index.mdx   | 15 +++++----------
 1 file changed, 5 insertions(+), 10 deletions(-)

diff --git a/packages/website/src/content/docs/docs/getting-started/index.mdx b/packages/website/src/content/docs/docs/getting-started/index.mdx
index fbfa72ba..ebe65e70 100644
--- a/packages/website/src/content/docs/docs/getting-started/index.mdx
+++ b/packages/website/src/content/docs/docs/getting-started/index.mdx
@@ -81,23 +81,18 @@ import * as Sentry from "@sentry/browser";
 
 Sentry.init({
   dsn: "https://spotlight@local/0", // Placeholder DSN
-  
-  // Enable Spotlight integration
+
+  // Enable Spotlight integration and comprehensive logging
   integrations: [
     Sentry.spotlightBrowserIntegration(),
-  ],
-  
-  // Capture 100% of transactions locally
-  tracesSampleRate: 1.0,
-  
-  // Enable comprehensive logging
-  integrations: [
     Sentry.captureConsoleIntegration({
       levels: ['log', 'info', 'warn', 'error', 'debug'],
     }),
   ],
+
+  // Capture 100% of transactions locally
+  tracesSampleRate: 1.0,
 });
-```
 
 ### Backend Applications