Docs
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
-
+
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 dc1fc101..26ced421 100644
--- a/packages/website/src/content/docs/docs/desktop-app/index.mdx
+++ b/packages/website/src/content/docs/docs/desktop-app/index.mdx
@@ -326,7 +326,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
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:
+
+
+
+ The fastest way to get started:
+
+ ```bash
+ npx @spotlightjs/spotlight
+ ```
+
+ This starts Spotlight on `http://localhost:8969` where you can access the web UI.
+
+
+ Download the Spotlight desktop application for the best experience:
+
+ Download for Mac
+
+ The desktop app includes:
+ - Dedicated window for debugging
+ - System tray integration
+ - Automatic updates
+ - Better performance
+
+
+ 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.
+
+
+ Run Spotlight in a container:
+
+ ```bash
+ docker run --rm -p 8969:8969 ghcr.io/getsentry/spotlight:latest
+ ```
+
+
+
+## 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
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.
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..b56df6cd
--- /dev/null
+++ b/packages/website/src/content/docs/docs/quickstart/nextjs.mdx
@@ -0,0 +1,337 @@
+---
+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 --spotlight
+```
+
+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
+
+
+
+ The quickest way to get started:
+
+ ```bash
+ npx @spotlightjs/spotlight
+ ```
+
+ This starts Spotlight on `http://localhost:8969` where you can access the web UI.
+
+
+ Install the Spotlight CLI globally:
+
+ ```bash
+ npm install -g @spotlightjs/spotlight
+ ```
+
+ Then run:
+
+ ```bash
+ spotlight
+ ```
+
+ This starts Spotlight on `http://localhost:8969` where you can access the web UI.
+
+
+ Download the Spotlight desktop application:
+
+ Download for Mac
+
+ The desktop app includes the sidecar and provides an enhanced interface for viewing events.
+
+
+ Run Spotlight in a container:
+
+ ```bash
+ docker run --rm -p 8969:8969 ghcr.io/getsentry/spotlight:latest
+ ```
+
+
+
+### 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.
+:::
+
+ use the `SENTRY_SPOTLIGHT` environment variable:
+
+```bash
+# In your .env.local file
+NEXT_PUBLIC_SENTRY_SPOTLIGHT=1 # for frontend event sending
+SENTRY_SPOTLIGHT=1 # for backend event sending
+```
+
+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 (
+
+
Test Spotlight
+
+
+ );
+}
+```
+
+Or for Pages Router:
+
+```typescript
+// pages/test-spotlight.tsx
+export default function TestSpotlight() {
+ const triggerError = () => {
+ throw new Error("Test error for Spotlight!");
+ };
+
+ return (
+
+
Test Spotlight
+
+
+ );
+}
+```
+
+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 (
+
+
+
+
+
+ );
+}
+```
+
+### 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 = (props) => {
+ return ;
+};
+
+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
+ });
+ ```
+
+### 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 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
+
+### 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
+
+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 9deb895f..00000000
--- a/packages/website/src/content/docs/docs/setup/index.mdx
+++ /dev/null
@@ -1,54 +0,0 @@
----
-title: Getting Started
-description: Choose how to run Spotlight in your development environment
-sidebar:
- order: 0
----
-
-import { Tabs, TabItem, LinkCard, CardGrid } from '@astrojs/starlight/components';
-import DownloadButton from '../../../../components/DownloadButton.astro';
-
-Spotlight offers several ways to run depending on your workflow and preferences. All options provide the same core debugging capabilities. Choose the one that fits best.
-
-## Three Ways to Run Spotlight
-:::tip[Combine Options]
-You can use multiple options together. For example, run the Desktop App for visual debugging while also connecting Cursor via MCP for AI-assisted debugging.
-:::
-| Option | Best For | Platform | UI |
-|--------|----------|----------|-----|
-| **Desktop App** | Visual debugging in a dedicated window | All platforms | Built-in |
-| **CLI** | Terminal workflows, wrapping apps, automation | All platforms | Browser |
-| **MCP Server** | AI-assisted debugging with Cursor, Claude, etc. | All platforms | none |
-
-
-
-
-
-
-
-
-
-
-## Next Steps
-
-After choosing your setup method, you may need to configure your application's Sentry SDK:
-
-
-
-Most SDKs automatically detect the `SENTRY_SPOTLIGHT` environment variable—just set it to `1` or the sidecar URL.