@danieljvdm/dev-kit 1.0.2 → 2.0.0

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

@@ -0,0 +1,110 @@
+# React Router Framework Features — Sentry React Router Framework SDK
+
+> Framework mode package: `@sentry/react-router`
+
+---
+
+## Wizard path
+
+Use the installer for fastest setup:
+
+```bash
+npx @sentry/wizard@latest -i reactRouter
+```
+
+The wizard can:
+
+- install SDK packages
+- expose `entry.client.tsx` and `entry.server.tsx`
+- create `instrument.server.mjs`
+- configure source maps in Vite/React Router config
+- add example verification files/routes
+
+---
+
+## Manual framework file checklist
+
+1. `entry.client.tsx` with:
+   - `Sentry.init(...)`
+   - `HydratedRouter onError={Sentry.sentryOnError}`
+2. `instrument.server.mjs` with server `Sentry.init(...)`
+3. `entry.server.tsx` with:
+   - `createSentryHandleRequest`
+   - `createSentryHandleError`
+4. Runtime startup with `NODE_OPTIONS='--import ./instrument.server.mjs'`
+
+---
+
+## Source maps for framework builds
+
+### Vite plugin
+
+```ts
+import { reactRouter } from "@react-router/dev/vite";
+import { sentryReactRouter } from "@sentry/react-router";
+
+export default defineConfig((config) => ({
+  plugins: [reactRouter(), sentryReactRouter(sentryConfig, config)],
+}));
+```
+
+### React Router build end hook
+
+```ts
+import { sentryOnBuildEnd } from "@sentry/react-router";
+
+export default {
+  ssr: true,
+  buildEnd: async ({ viteConfig, reactRouterConfig, buildManifest }) => {
+    await sentryOnBuildEnd({ viteConfig, reactRouterConfig, buildManifest });
+  },
+};
+```
+
+### Auth token
+
+Use `SENTRY_AUTH_TOKEN` via environment variables (or `.env.sentry-build-plugin`).
+
+---
+
+## Runtime startup strategies
+
+### Preferred (`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 (direct import)
+
+If runtime flags are unavailable, import server instrumentation at the top of
+`entry.server.tsx`:
+
+```tsx
+import "./instrument.server.mjs";
+```
+
+This fallback may have incomplete automatic instrumentation compared to `--import`.
+
+---
+
+## Non-framework handoff
+
+If project uses React Router in data/declarative mode without framework entry wrappers,
+route setup to [`react`](../react/index.md) (`@sentry/react`) for v5/v6/v7 integrations.
+
+---
+
+## Troubleshooting
+
+| Issue                                     | Solution                                                                           |
+| ----------------------------------------- | ---------------------------------------------------------------------------------- |
+| Entry files not present                   | Run `npx react-router reveal`                                                      |
+| Source maps still minified                | Confirm both `sentryReactRouter` plugin and `sentryOnBuildEnd` hook are configured |
+| Server startup misses instrumentation     | Ensure `NODE_OPTIONS --import` is actually applied in deployed runtime             |
+| Framework setup used in non-framework app | Switch to [`react`](../react/index.md) guidance                                    |

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

@@ -0,0 +1,67 @@
+# Session Replay — Sentry React Router Framework SDK
+
+> Minimum SDK: `@sentry/react-router` with Replay support
+
+---
+
+## Replay setup (client)
+
+Configure replay in `entry.client.tsx`:
+
+```tsx
+import * as Sentry from "@sentry/react-router";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [Sentry.replayIntegration()],
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0,
+});
+```
+
+---
+
+## Sampling guidance
+
+| Goal                  | Suggested setup                                                  |
+| --------------------- | ---------------------------------------------------------------- |
+| Validate integration  | `replaysSessionSampleRate: 0.1`, `replaysOnErrorSampleRate: 1.0` |
+| Control storage costs | Lower session sample rate; keep error replay rate high           |
+| Incident debugging    | Temporarily increase session sample rate                         |
+
+---
+
+## Privacy controls
+
+```tsx
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [
+    Sentry.replayIntegration({
+      maskAllText: true,
+      blockAllMedia: true,
+    }),
+  ],
+  replaysSessionSampleRate: 0.1,
+  replaysOnErrorSampleRate: 1.0,
+});
+```
+
+---
+
+## Verification
+
+1. Use the app in a browser and trigger an error.
+2. Open **Replays** in Sentry.
+3. Confirm replay exists and is linked to errors/traces.
+
+---
+
+## Troubleshooting
+
+| Issue                   | Solution                                                    |
+| ----------------------- | ----------------------------------------------------------- |
+| Replay missing          | Ensure `replayIntegration()` is configured in client init   |
+| Only error replays show | Increase `replaysSessionSampleRate`                         |
+| Sensitive data visible  | Enable masking/blocking and verify element privacy settings |
+| Replay volume too high  | Lower replay sampling rates                                 |

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

@@ -0,0 +1,96 @@
+# Tracing — Sentry React Router Framework SDK
+
+> Minimum SDK: `@sentry/react-router` (beta)
+
+---
+
+## Enable tracing
+
+Configure tracing in `entry.client.tsx`:
+
+```tsx
+import * as Sentry from "@sentry/react-router";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [Sentry.reactRouterTracingIntegration()],
+  tracesSampleRate: 1.0,
+  tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/],
+});
+```
+
+---
+
+## Sampling guidance
+
+| Environment                | Suggested value                         |
+| -------------------------- | --------------------------------------- |
+| Development/testing        | `tracesSampleRate: 1.0`                 |
+| Initial production rollout | `0.1` to `0.3`                          |
+| High throughput            | Use lower fixed rate or `tracesSampler` |
+
+If both `tracesSampleRate` and `tracesSampler` are provided, `tracesSampler` takes
+precedence.
+
+---
+
+## Distributed tracing
+
+Use `tracePropagationTargets` so Sentry sends trace headers to your backend routes:
+
+```tsx
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [Sentry.reactRouterTracingIntegration()],
+  tracesSampleRate: 0.2,
+  tracePropagationTargets: [/^\//, /^https:\/\/api\.example\.com/],
+});
+```
+
+---
+
+## Custom spans
+
+```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!");
+    },
+  );
+}
+```
+
+---
+
+## Node runtime note
+
+Automatic server-side instrumentation compatibility has version limits for some Node
+versions in current docs.
+If your runtime is outside supported auto-instrumentation ranges, use framework
+instrumentation APIs or manual wrappers to keep tracing coverage.
+
+---
+
+## Verification
+
+1. Trigger one loader/action request from the app.
+2. Open **Traces** in Sentry.
+3. Confirm transaction names, spans, and linked errors appear.
+
+---
+
+## Troubleshooting
+
+| Issue                                      | Solution                                                                        |
+| ------------------------------------------ | ------------------------------------------------------------------------------- |
+| No trace data                              | Confirm `reactRouterTracingIntegration()` and `tracesSampleRate` are configured |
+| Client and server traces not connected     | Adjust `tracePropagationTargets` to include backend URLs                        |
+| Too many traces                            | Lower sample rate or use `tracesSampler`                                        |
+| Tracing disappears in certain environments | Check runtime version constraints and fallback instrumentation path             |

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

@@ -0,0 +1,71 @@
+# User Feedback — Sentry React Router Framework SDK
+
+> Minimum SDK: `@sentry/react-router` with Feedback support
+
+---
+
+## Feedback widget setup
+
+Configure in `entry.client.tsx`:
+
+```tsx
+import * as Sentry from "@sentry/react-router";
+
+Sentry.init({
+  dsn: "___PUBLIC_DSN___",
+  integrations: [
+    Sentry.feedbackIntegration({
+      colorScheme: "system",
+    }),
+  ],
+});
+```
+
+---
+
+## Common options
+
+```tsx
+Sentry.feedbackIntegration({
+  autoInject: true,
+  colorScheme: "system",
+  showName: true,
+  showEmail: true,
+  triggerLabel: "Report a bug",
+  formTitle: "Report a bug",
+  submitButtonLabel: "Send report",
+  successMessageText: "Thanks for the report.",
+});
+```
+
+---
+
+## Error-linked feedback dialog
+
+```tsx
+const eventId = Sentry.captureException(new Error("Checkout failed"));
+Sentry.showReportDialog({
+  eventId,
+  title: "Something went wrong",
+  subtitle: "Tell us what happened",
+});
+```
+
+---
+
+## Verification
+
+1. Trigger feedback widget submission from the app.
+2. Open **User Feedback** in Sentry.
+3. Confirm submissions appear and error-linked reports attach to events.
+
+---
+
+## Troubleshooting
+
+| Issue                         | Solution                                                 |
+| ----------------------------- | -------------------------------------------------------- |
+| Feedback widget not visible   | Ensure `feedbackIntegration()` is in client integrations |
+| Missing user context          | Set Sentry user context before submitting feedback       |
+| Feedback not linked to errors | Use `showReportDialog` with a real `eventId`             |
+| UI overlap/z-index issues     | Adjust app styles and trigger placement                  |

package/skills/sentry/references/sdks/ruby/crons.md

@@ -0,0 +1,184 @@
+# Crons — Sentry Ruby SDK
+
+> Minimum SDK: `sentry-ruby` v5.14.0+
+
+Cron monitoring detects missed, failed, or slow scheduled jobs by capturing check-in
+events at job start and completion.
+Each check-in pair creates a monitor timeline in Sentry — if the `:ok` check-in doesn’t
+arrive on time, Sentry raises an alert.
+
+## Contents
+
+- [Manual check-ins](#manual-check-ins)
+- [ActiveJob integration](#activejob-integration)
+- [Sidekiq-Cron integration](#sidekiq-cron-integration)
+- [Upserting monitor configuration](#upserting-monitor-configuration)
+- [Completion-only check-in](#completion-only-check-in)
+- [Best Practices](#best-practices)
+- [Troubleshooting](#troubleshooting)
+
+## Manual Check-Ins
+
+Use when the scheduler is Clockwork, Whenever, a plain Ruby loop, or any framework
+without a built-in integration:
+
+```ruby
+# Start check-in — save the returned ID
+check_in_id = Sentry.capture_check_in("daily-report", :in_progress)
+
+begin
+  GenerateDailyReport.run
+  Sentry.capture_check_in("daily-report", :ok, check_in_id: check_in_id)
+rescue => e
+  Sentry.capture_check_in("daily-report", :error, check_in_id: check_in_id)
+  Sentry.capture_exception(e)
+  raise
+end
+```
+
+**Monitor slug** must match the slug configured in Sentry.
+Slugs are unique per project and environment.
+
+**Status values:**
+
+| Status         | When to use                |
+| -------------- | -------------------------- |
+| `:in_progress` | Job has started            |
+| `:ok`          | Job completed successfully |
+| `:error`       | Job failed                 |
+
+## ActiveJob Integration
+
+Include `Sentry::Cron::MonitorCheckIns` to auto-capture check-ins for any ActiveJob:
+
+```ruby
+class NightlyCleanupJob < ApplicationJob
+  include Sentry::Cron::MonitorCheckIns
+  sentry_monitor_check_ins
+
+  def perform
+    User.inactive.delete_old_accounts
+  end
+end
+```
+
+Customize the slug and schedule:
+
+```ruby
+class NightlyCleanupJob < ApplicationJob
+  include Sentry::Cron::MonitorCheckIns
+  sentry_monitor_check_ins(
+    slug: "nightly-cleanup",
+    monitor_config: Sentry::Cron::MonitorConfig.from_crontab(
+      "0 2 * * *",
+      checkin_margin: 5,   # minutes before marking missed
+      max_runtime: 30,     # minutes before marking timed out
+      timezone: "UTC"
+    )
+  )
+
+  def perform
+    User.inactive.delete_old_accounts
+  end
+end
+```
+
+## Sidekiq-Cron Integration
+
+Enable automatic check-ins for all Sidekiq-Cron periodic jobs with a single patch:
+
+```ruby
+Sentry.init do |config|
+  config.dsn = ENV["SENTRY_DSN"]
+  config.enabled_patches += [:sidekiq_cron]
+end
+```
+
+Sentry captures check-ins for every job defined in your Sidekiq-Cron schedule
+automatically — no per-job changes needed.
+
+## Upserting Monitor Configuration
+
+Pass `monitor_config` in the initial check-in to create or update the monitor definition
+programmatically (no manual setup in Sentry UI required):
+
+```ruby
+monitor_config = Sentry::Cron::MonitorConfig.from_crontab(
+  "5 * * * *",       # runs at :05 every hour
+  checkin_margin: 5,
+  max_runtime: 15,
+  timezone: "Europe/Berlin"
+)
+
+check_in_id = Sentry.capture_check_in(
+  "hourly-sync",
+  :in_progress,
+  monitor_config: monitor_config
+)
+# ... do work ...
+Sentry.capture_check_in("hourly-sync", :ok, check_in_id: check_in_id)
+```
+
+### Schedule Types
+
+**Crontab:**
+
+```ruby
+Sentry::Cron::MonitorConfig.from_crontab(
+  "0 9 * * 1-5",   # 9am weekdays
+  checkin_margin: 10,
+  max_runtime: 60,
+  timezone: "America/New_York"
+)
+```
+
+**Interval:**
+
+```ruby
+Sentry::Cron::MonitorConfig.from_interval(
+  30, :minute,     # every 30 minutes
+  checkin_margin: 5,
+  max_runtime: 25
+)
+```
+
+Supported interval units: `:minute`, `:hour`, `:day`, `:week`, `:month`, `:year`
+
+## Completion-Only Check-In
+
+For jobs where only missed-schedule detection matters (not duration), send a single
+`:ok` check-in at job completion instead of the two-step `:in_progress` / `:ok` pair:
+
+```ruby
+def run_health_ping
+  ping_all_services
+  Sentry.capture_check_in("health-ping", :ok)
+end
+```
+
+This detects when a job doesn’t run at all but cannot detect stuck or long-running jobs
+— there is no `:in_progress` marker, so Sentry has no start time to measure against
+`max_runtime`. Use the full two-step pattern for jobs where duration matters.
+
+## Best Practices
+
+- Use the two-step `:in_progress` / `:ok` pattern for all long-running jobs — it catches
+  both missed runs and jobs that started but never finished
+- Set `checkin_margin` a few minutes above the expected cron interval jitter
+- Set `max_runtime` conservatively — it’s better to alert early on a runaway job than to
+  miss it
+- Use `monitor_config` upsert in the job itself rather than configuring monitors
+  manually in the Sentry UI — this keeps schedule definitions in code
+- Ensure `SENTRY_DSN` is set in the environment where cron jobs run (often different
+  from the web process)
+
+## Troubleshooting
+
+| Issue                              | Solution                                                                                            |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Check-ins not appearing            | Verify `SENTRY_DSN` is set in the cron job’s environment (separate from web server)                 |
+| Monitor shows “missed” immediately | `checkin_margin` too low; increase it to account for scheduler jitter                               |
+| `capture_check_in` returns `nil`   | SDK not initialized — ensure `Sentry.init` runs before the job                                      |
+| ActiveJob mixin not capturing      | Confirm `include Sentry::Cron::MonitorCheckIns` and `sentry_monitor_check_ins` are both present     |
+| Sidekiq-Cron not auto-capturing    | Ensure `config.enabled_patches += [:sidekiq_cron]` is in `Sentry.init`; requires `sidekiq-cron` gem |
+| Duplicate check-in pairs           | Check that `capture_check_in` is not called in both the mixin and manual code for the same job      |