@danieljvdm/dev-kit 1.0.2 → 2.0.0

package/skills/sentry/references/sdks/react-router-framework/error-monitoring.md

@@ -0,0 +1,127 @@
+# Error Monitoring — Sentry React Router Framework SDK
+
+> Minimum SDK: `@sentry/react-router` (beta)
+
+---
+
+## Automatic and Manual Capture
+
+| Area                          | Auto Captured? | Mechanism                                                     |
+| ----------------------------- | -------------- | ------------------------------------------------------------- |
+| Client-side framework errors  | ✅ Yes         | `HydratedRouter onError={Sentry.sentryOnError}`               |
+| Unhandled client exceptions   | ✅ Yes         | Browser global handlers from SDK init                         |
+| Server request/render errors  | ✅ Yes         | `createSentryHandleRequest` + `createSentryHandleError`       |
+| Custom handled server errors  | ❌ Not always  | Call `Sentry.captureException` manually                       |
+| Custom loader/action failures | ⚠️ Depends     | Use `wrapServerLoader` / `wrapServerAction` or manual capture |
+
+---
+
+## Client setup requirement
+
+`entry.client.tsx` must include:
+
+```tsx
+import * as Sentry from "@sentry/react-router";
+import { HydratedRouter } from "react-router/dom";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+});
+
+hydrateRoot(document, <HydratedRouter onError={Sentry.sentryOnError} />);
+```
+
+Without `sentryOnError`, framework-level client errors may be missed.
+
+---
+
+## Server setup requirement
+
+`entry.server.tsx`:
+
+```tsx
+import * as Sentry from "@sentry/react-router";
+import { createReadableStreamFromReadable } from "@react-router/node";
+import { renderToPipeableStream } from "react-dom/server";
+import { ServerRouter } from "react-router";
+
+const handleRequest = Sentry.createSentryHandleRequest({
+  ServerRouter,
+  renderToPipeableStream,
+  createReadableStreamFromReadable,
+});
+
+export default handleRequest;
+
+export const handleError = Sentry.createSentryHandleError({
+  logErrors: false,
+});
+```
+
+---
+
+## Manual capture in custom handlers
+
+```tsx
+import * as Sentry from "@sentry/react-router";
+
+export function handleError(error: unknown, args: unknown) {
+  Sentry.captureException(error);
+  console.error(error);
+}
+```
+
+For custom streaming request implementations, wrap your handler:
+
+```tsx
+import { wrapSentryHandleRequest } from "@sentry/react-router";
+
+export default wrapSentryHandleRequest(customHandleRequest);
+```
+
+---
+
+## Loader/action wrappers
+
+```ts
+import * as Sentry from "@sentry/react-router";
+
+export const loader = Sentry.wrapServerLoader(
+  { name: "Load Data", description: "Loads route data" },
+  async () => {
+    // loader logic
+  },
+);
+
+export const action = Sentry.wrapServerAction(
+  { name: "Submit Data", description: "Handles form submission" },
+  async () => {
+    // action logic
+  },
+);
+```
+
+---
+
+## Verification
+
+Use a route loader that throws:
+
+```tsx
+export async function loader() {
+  throw new Error("My first Sentry error!");
+}
+```
+
+Open the route and verify the event appears in **Issues**.
+
+---
+
+## Troubleshooting
+
+| Issue                                   | Solution                                                                           |
+| --------------------------------------- | ---------------------------------------------------------------------------------- |
+| Client framework errors missing         | Ensure `HydratedRouter` uses `onError={Sentry.sentryOnError}`                      |
+| Server render/request errors missing    | Verify both `createSentryHandleRequest` and `createSentryHandleError` are exported |
+| Custom handlers not captured            | Add explicit `captureException` calls                                              |
+| Error appears locally but not in Sentry | Check DSN, network restrictions, and `debug: true` output                          |

package/skills/sentry/references/sdks/react-router-framework/index.md

@@ -0,0 +1,411 @@
+# Sentry React Router Framework SDK
+
+Opinionated wizard that scans your React Router Framework project and guides you through
+complete Sentry setup across client and server entry points.
+
+> **Important:** This SDK is currently beta.
+> For React Router non-framework/data/declarative mode (v5/v6/v7), use
+> [`react`](../react/index.md) with `@sentry/react` integrations instead.
+
+---
+
+## Phase 1: Detect
+
+Run these commands to understand the project before making any recommendations:
+
+```bash
+# Detect React Router Framework indicators and versions
+cat package.json | grep -E '"react-router"|"@react-router/"|"react-router-dev"|"react-router-serve"'
+
+# Detect Sentry package choice
+cat package.json | grep -E '"@sentry/react-router"|"@sentry/react"|"@sentry/profiling-node"'
+
+# Check entry point visibility and server instrumentation files
+ls entry.client.tsx entry.server.tsx instrument.server.mjs react-router.config.ts vite.config.ts 2>/dev/null
+
+# Check if React Router files are still hidden (framework mode helper command available)
+cat package.json | grep -E '"reveal"|react-router'
+
+# Detect runtime startup scripts and import strategy
+cat package.json | grep -E '"dev"|"start"|NODE_OPTIONS|--import'
+
+# Detect optional logging/profile-related dependencies
+cat package.json | grep -E '"pino"|"winston"|"@sentry/profiling-node"'
+
+# Detect companion backend directories
+ls ../backend ../server ../api 2>/dev/null
+cat ../go.mod ../requirements.txt ../Gemfile ../pom.xml 2>/dev/null | head -3
+```
+
+**What to determine:**
+
+| Question                                        | Impact                                                                         |
+| ----------------------------------------------- | ------------------------------------------------------------------------------ |
+| `@sentry/react-router` already installed?       | Skip install and move to feature setup                                         |
+| Framework entry files exposed?                  | Need `npx react-router reveal` before manual config                            |
+| Using `@sentry/react` instead?                  | This is likely non-framework routing; redirect to [`react`](../react/index.md) |
+| `react-router.config.ts` + Vite config present? | Source map upload and build-end hook setup path                                |
+| `NODE_OPTIONS --import` available?              | Preferred server instrumentation startup path                                  |
+| `@sentry/profiling-node` desired/available?     | Enable server profiling integration                                            |
+| Backend directory found?                        | Trigger Phase 4 cross-link suggestion                                          |
+
+---
+
+## Phase 2: Recommend
+
+Present a concrete recommendation based on what you found.
+Do not ask open-ended questions — lead with a proposal:
+
+**Recommended (core coverage):**
+
+- ✅ **Error Monitoring** — always; captures client and server errors with framework
+  hooks
+- ✅ **Tracing** — recommended baseline in framework apps with client/server request flow
+- ✅ **Session Replay** — recommended for user-facing applications
+
+**Optional (enhanced observability):**
+
+- ⚡ **Profiling** — server-side profiling with `@sentry/profiling-node`
+- ⚡ **Logs** — structured `Sentry.logger.*` ingestion and correlation
+- ⚡ **User Feedback** — in-app feedback widget/reporting flows
+
+**Recommendation logic:**
+
+| Feature          | Recommend when …                                                              |
+| ---------------- | ----------------------------------------------------------------------------- |
+| Error Monitoring | **Always** — non-negotiable baseline                                          |
+| Tracing          | **Usually yes** in framework apps; route and request timing is high-value     |
+| Session Replay   | User-facing product or difficult UX debugging                                 |
+| Profiling        | Server performance investigations needed; Node runtime compatibility verified |
+| Logs             | Team wants log-search and trace correlation in Sentry                         |
+| User Feedback    | Product/support teams need direct in-app issue reports                        |
+
+Propose: _“I recommend Error Monitoring + Tracing + Session Replay first.
+Want me to also enable Profiling, Logs, and User Feedback?”_
+
+---
+
+## Phase 3: Guide
+
+### Option 1: Wizard (Recommended)
+
+> **You need to run this yourself** — the wizard is interactive and may require browser
+> login:
+>
+> ```bash
+> npx @sentry/wizard@latest -i reactRouter
+> ```
+>
+> It installs `@sentry/react-router`, exposes React Router entry files, creates
+> instrumentation files, updates root error handling, configures source map upload, and
+> adds verification examples.
+>
+> **Once it finishes, continue at [Verification](#verification).**
+
+If the user skips wizard setup, continue with manual setup below.
+
+---
+
+### Option 2: Manual Setup
+
+#### Install packages
+
+```bash
+npm install @sentry/react-router --save
+```
+
+If profiling is needed:
+
+```bash
+npm install @sentry/profiling-node --save
+```
+
+#### Expose framework entry files
+
+```bash
+npx react-router reveal
+```
+
+#### Configure client in `entry.client.tsx`
+
+```tsx
+import * as Sentry from "@sentry/react-router";
+import { startTransition, StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { HydratedRouter } from "react-router/dom";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  dataCollection: {
+    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
+    // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#dataCollection
+    // userInfo: false,
+    // httpBodies: [],
+  },
+  integrations: [
+    Sentry.reactRouterTracingIntegration(),
+    Sentry.replayIntegration(),
+    Sentry.feedbackIntegration({ colorScheme: "system" }),
+  ],
+  enableLogs: true,
+  tracesSampleRate: 1.0,
+  tracePropagationTargets: [/^\//, /^https:\/\/yourserver\.io\/api/],
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0,
+});
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <HydratedRouter onError={Sentry.sentryOnError} />
+    </StrictMode>,
+  );
+});
+```
+
+#### Configure server in `instrument.server.mjs`
+
+```javascript
+import * as Sentry from "@sentry/react-router";
+import { nodeProfilingIntegration } from "@sentry/profiling-node";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  dataCollection: {
+    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
+    // https://docs.sentry.io/platforms/javascript/guides/react-router/configuration/options/#dataCollection
+    // userInfo: false,
+    // httpBodies: [],
+  },
+  enableLogs: true,
+  integrations: [nodeProfilingIntegration()],
+  tracesSampleRate: 1.0,
+  profileSessionSampleRate: 1.0,
+});
+```
+
+#### Wrap server handlers in `entry.server.tsx`
+
+```tsx
+import * as Sentry from "@sentry/react-router";
+import { createReadableStreamFromReadable } from "@react-router/node";
+import { renderToPipeableStream } from "react-dom/server";
+import { ServerRouter } from "react-router";
+
+const handleRequest = Sentry.createSentryHandleRequest({
+  ServerRouter,
+  renderToPipeableStream,
+  createReadableStreamFromReadable,
+});
+
+export default handleRequest;
+
+export const handleError = Sentry.createSentryHandleError({
+  logErrors: false,
+});
+```
+
+For custom server logic, use `wrapSentryHandleRequest`, `getMetaTagTransformer`, and
+manual `Sentry.captureException` in your custom `handleError`.
+
+#### Load server instrumentation on startup
+
+Prefer `NODE_OPTIONS --import`:
+
+```json
+{
+  "scripts": {
+    "dev": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router dev",
+    "start": "NODE_OPTIONS='--import ./instrument.server.mjs' react-router-serve ./build/server/index.js"
+  }
+}
+```
+
+Fallback for platforms where runtime flags are restricted:
+
+```tsx
+import "./instrument.server.mjs";
+```
+
+This direct-import method can result in incomplete auto-instrumentation compared to
+`--import`.
+
+#### Configure source maps
+
+`vite.config.ts`:
+
+```typescript
+import { reactRouter } from "@react-router/dev/vite";
+import { sentryReactRouter, type SentryReactRouterBuildOptions } from "@sentry/react-router";
+import { defineConfig } from "vite";
+
+const sentryConfig: SentryReactRouterBuildOptions = {
+  org: "___ORG_SLUG___",
+  project: "___PROJECT_SLUG___",
+  authToken: process.env.SENTRY_AUTH_TOKEN,
+};
+
+export default defineConfig((config) => {
+  return {
+    plugins: [reactRouter(), sentryReactRouter(sentryConfig, config)],
+  };
+});
+```
+
+`react-router.config.ts`:
+
+```typescript
+import type { Config } from "@react-router/dev/config";
+import { sentryOnBuildEnd } from "@sentry/react-router";
+
+export default {
+  ssr: true,
+  buildEnd: async ({ viteConfig, reactRouterConfig, buildManifest }) => {
+    await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest });
+  },
+} satisfies Config;
+```
+
+---
+
+### For Each Agreed Feature
+
+Walk through features one at a time.
+Load the reference file, follow steps exactly, and verify before moving on:
+
+| Feature            | Reference                              | Load when …                                                 |
+| ------------------ | -------------------------------------- | ----------------------------------------------------------- |
+| Error Monitoring   | `./error-monitoring.md`                | Always                                                      |
+| Tracing            | `./tracing.md`                         | Route/request performance visibility needed                 |
+| Profiling          | `./profiling.md`                       | Server performance analysis needed                          |
+| Session Replay     | `./session-replay.md`                  | User-facing app                                             |
+| Logs               | `./logging.md`                         | Structured logs/correlation needed                          |
+| User Feedback      | `./user-feedback.md`                   | In-app feedback flows needed                                |
+| Framework Features | `./react-router-framework-features.md` | Entry files, wrappers, source maps, startup import strategy |
+
+For each feature: `Read ./<feature>.md`, follow steps exactly, verify it works.
+
+---
+
+## Configuration Reference
+
+### Key `Sentry.init()` options
+
+| Option                       | Type                   | Default                             | Notes                                                                  |
+| ---------------------------- | ---------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
+| `dsn`                        | `string`               | —                                   | Required; SDK disabled when empty                                      |
+| `dataCollection`             | `object`               | —                                   | Controls what data is collected (userInfo, cookies, httpHeaders, etc.) |
+| `dataCollection.userInfo`    | `boolean`              | `true`                              | Includes IP-derived user context                                       |
+| `dataCollection.cookies`     | `CollectBehavior`      | `true`                              | Controls cookie collection and filtering                               |
+| `dataCollection.httpHeaders` | `object`               | `{ request: true, response: true }` | Controls HTTP header collection                                        |
+| `sendDefaultPii`             | `boolean`              | `false`                             | **Deprecated:** Use `dataCollection` instead; removed in v11           |
+| `integrations`               | `Integration[]`        | SDK defaults                        | Add tracing/replay/feedback/profiling integrations                     |
+| `enableLogs`                 | `boolean`              | `false`                             | Enables `Sentry.logger.*` ingestion                                    |
+| `tracesSampleRate`           | `number`               | —                                   | Usually `1.0` in testing, lower in production                          |
+| `tracePropagationTargets`    | `(string \| RegExp)[]` | SDK defaults                        | URLs that receive tracing headers                                      |
+| `replaysSessionSampleRate`   | `number`               | —                                   | Fraction of all sessions recorded                                      |
+| `replaysOnErrorSampleRate`   | `number`               | —                                   | Fraction of error sessions recorded                                    |
+| `profileSessionSampleRate`   | `number`               | —                                   | Fraction of transactions profiled (server profiling)                   |
+| `tunnel`                     | `string`               | —                                   | Optional ad-blocker bypass endpoint                                    |
+| `debug`                      | `boolean`              | `false`                             | Verbose SDK diagnostics                                                |
+
+### Framework-specific APIs
+
+| API                                               | Purpose                                                  |
+| ------------------------------------------------- | -------------------------------------------------------- |
+| `reactRouterTracingIntegration()`                 | Client-side tracing integration for framework mode       |
+| `sentryOnError`                                   | Hooks into React Router `HydratedRouter` error reporting |
+| `createSentryHandleRequest(...)`                  | Server request wrapper for framework entry server        |
+| `createSentryHandleError(...)`                    | Server error handler wrapper                             |
+| `wrapServerLoader(...)` / `wrapServerAction(...)` | Manual wrapping for server loaders/actions               |
+| `sentryReactRouter(...)`                          | Vite plugin for source maps/build integration            |
+| `sentryOnBuildEnd(...)`                           | React Router build-end hook for source map processing    |
+
+---
+
+## Verification
+
+### Wizard-generated path
+
+If wizard examples were generated, open `/sentry-example-page` and trigger test actions.
+
+### Manual error test
+
+```tsx
+export async function loader() {
+  throw new Error("My first Sentry error!");
+}
+```
+
+### Manual tracing test
+
+```tsx
+import * as Sentry from "@sentry/react-router";
+
+export async function loader() {
+  return Sentry.startSpan({ op: "test", name: "My First Test Transaction" }, () => {
+    throw new Error("My first Sentry error!");
+  });
+}
+```
+
+### Logs test
+
+```javascript
+Sentry.logger.info("User example action completed");
+Sentry.logger.warn("Slow operation detected", { operation: "data_fetch", duration: 3500 });
+Sentry.logger.error("Validation failed", { field: "email", reason: "Invalid email" });
+```
+
+Confirm in Sentry:
+
+- **Issues**: errors appear
+- **Traces**: transaction/span data appears
+- **Profiles**: profiles appear when profiling enabled
+- **Replays**: replay entries appear when enabled
+- **Logs**: log events appear when `enableLogs: true`
+- **User Feedback**: submissions appear when feedback enabled
+
+---
+
+## Phase 4: Cross-Link
+
+After completing React Router Framework setup:
+
+1. Check whether the app is actually non-framework routing (v5/v6/v7 data/declarative
+   with `@sentry/react`).
+2. If yes, redirect to [`react`](../react/index.md) for non-framework routing
+   integrations.
+
+Then check companion backend coverage:
+
+```bash
+ls ../backend ../server ../api ../go ../python 2>/dev/null
+cat ../go.mod ../requirements.txt ../pyproject.toml ../Gemfile ../pom.xml 2>/dev/null | head -5
+```
+
+| Backend detected      | Suggest skill                  |
+| --------------------- | ------------------------------ |
+| Go                    | [`go`](../go/index.md)         |
+| Python                | [`python`](../python/index.md) |
+| Ruby                  | [`ruby`](../ruby/index.md)     |
+| Node backend services | [`node`](../node/index.md)     |
+| Java services         | Use `@sentry/java` docs        |
+
+---
+
+## Troubleshooting
+
+| Issue                                                    | Solution                                                                                   |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `entry.client.tsx` / `entry.server.tsx` missing          | Run `npx react-router reveal` first                                                        |
+| Client errors missing                                    | Ensure `HydratedRouter` includes `onError={Sentry.sentryOnError}`                          |
+| Server errors missing                                    | Use `createSentryHandleRequest` and `createSentryHandleError` wrappers                     |
+| Custom server handlers bypass Sentry                     | Use `wrapSentryHandleRequest` and manual `captureException` in custom `handleError`        |
+| Source maps not uploaded                                 | Verify `sentryReactRouter` plugin config and `sentryOnBuildEnd` hook                       |
+| `SENTRY_AUTH_TOKEN` undefined in Vite config             | Load env vars in config or use `.env.sentry-build-plugin`                                  |
+| Incomplete server auto-instrumentation                   | Prefer `NODE_OPTIONS='--import ./instrument.server.mjs'` startup                           |
+| Profiling data missing                                   | Confirm `@sentry/profiling-node` installed and `nodeProfilingIntegration` enabled          |
+| Running unsupported Node auto-instrumentation version    | Use instrumentation API/manual wrappers as documented                                      |
+| Non-framework app configured with `@sentry/react-router` | Switch to [`react`](../react/index.md) + `@sentry/react` for v5/v6/v7 non-framework routes |

package/skills/sentry/references/sdks/react-router-framework/logging.md

@@ -0,0 +1,66 @@
+# Logs — Sentry React Router Framework SDK
+
+> Minimum SDK: `@sentry/react-router` with Logs support
+
+---
+
+## Enable logs
+
+Set `enableLogs: true` in both client and server initialization where you want log
+ingestion.
+
+```tsx
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  enableLogs: true,
+});
+```
+
+---
+
+## Logging APIs
+
+```javascript
+Sentry.logger.info("User example action completed");
+
+Sentry.logger.warn("Slow operation detected", {
+  operation: "data_fetch",
+  duration: 3500,
+});
+
+Sentry.logger.error("Validation failed", {
+  field: "email",
+  reason: "Invalid email",
+});
+```
+
+---
+
+## Correlation guidance
+
+For better debugging:
+
+1. Enable tracing with meaningful transaction names.
+2. Add structured fields to logs (`operation`, `route`, `tenant`, `requestId`).
+3. Keep consistent keys across client and server logs.
+
+This improves issue/trace/log correlation in Sentry.
+
+---
+
+## Verification
+
+1. Emit info/warn/error logs from app code.
+2. Open **Logs** in Sentry.
+3. Filter by message/metadata and confirm ingestion.
+
+---
+
+## Troubleshooting
+
+| Issue                     | Solution                                                       |
+| ------------------------- | -------------------------------------------------------------- |
+| Logs not visible          | Verify `enableLogs: true` in active init path                  |
+| Missing metadata          | Pass structured objects as second logger argument              |
+| Noisy logs                | Reduce volume or gate lower-severity logs by environment       |
+| Logs not linked to traces | Ensure tracing is active and shared context fields are present |

package/skills/sentry/references/sdks/react-router-framework/profiling.md

@@ -0,0 +1,57 @@
+# Profiling — Sentry React Router Framework SDK
+
+> Minimum SDK: `@sentry/react-router` with `@sentry/profiling-node` for server profiling
+
+---
+
+## Profiling setup (server)
+
+Install profiling package:
+
+```bash
+npm install @sentry/profiling-node --save
+```
+
+Configure in `instrument.server.mjs`:
+
+```js
+import * as Sentry from "@sentry/react-router";
+import { nodeProfilingIntegration } from "@sentry/profiling-node";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [nodeProfilingIntegration()],
+  tracesSampleRate: 1.0,
+  profileSessionSampleRate: 1.0,
+});
+```
+
+---
+
+## Sampling strategy
+
+| Setting                    | Purpose                                           |
+| -------------------------- | ------------------------------------------------- |
+| `tracesSampleRate`         | How many transactions are captured                |
+| `profileSessionSampleRate` | What fraction of traced transactions get profiles |
+
+Start high in development, then lower for production cost control.
+
+---
+
+## Verification
+
+1. Trigger a server transaction with profiling enabled.
+2. Open **Profiles** in Sentry.
+3. Confirm profile entries appear and are linked to transactions.
+
+---
+
+## Troubleshooting
+
+| Issue                            | Solution                                                               |
+| -------------------------------- | ---------------------------------------------------------------------- |
+| No profiles visible              | Ensure `@sentry/profiling-node` is installed and integration is active |
+| Traces visible but no profiles   | Increase `profileSessionSampleRate`                                    |
+| Profile volume too high          | Lower `profileSessionSampleRate` and/or `tracesSampleRate`             |
+| Runtime incompatibility symptoms | Verify Node runtime support and fallback to tracing-only where needed  |