TypeScript Sentry
This skill covers the SDK-side work: capture, spans, cron monitors, source maps, profiling, filtering. For project-level Sentry compliance (DSN hygiene, sourcemap-upload wiring in CI) use /configure:sentry; for local step-through debugging use typescript-debugging.
Core Expertise
Sentry provides error monitoring and performance tracking:
- Automatic error capture with stack traces
- Performance monitoring with distributed tracing
- Cron job monitoring for scheduled tasks
- Source map integration for readable TypeScript traces
- Rich context with tags, breadcrumbs, and user data
- Structured logging forwarded to Sentry (
enableLogs)
- CPU/JS profiling (Node.js + browser)
- Session replay with privacy controls
- User feedback widget
- Enrichment helpers (custom contexts, breadcrumb categories, fingerprinting)
Installation
Bun
bun add @sentry/bun
Node.js
bun add @sentry/node
Next.js
bun add @sentry/nextjs @sentry/profiling-node
React/Browser
bun add @sentry/react
# or
bun add @sentry/browser
Error Capturing
captureException
try {
await riskyOperation();
} catch (error) {
Sentry.captureException(error);
throw error; // Re-throw if needed
}
With Context
Sentry.captureException(error, {
tags: {
feature: "checkout",
paymentProvider: "stripe",
},
extra: {
orderId: order.id,
userId: user.id,
cartItems: cart.items.length,
},
level: "error", // fatal, error, warning, info, debug
});
captureMessage
// Simple message
Sentry.captureMessage("User completed onboarding");
// With level
Sentry.captureMessage("Rate limit approaching", "warning");
// With context
Sentry.captureMessage("Payment failed", {
level: "error",
tags: { gateway: "stripe" },
extra: { errorCode: "card_declined" },
});
Agentic Optimizations
| Context |
Command |
| Install Bun |
bun add @sentry/bun |
| Install Node |
bun add @sentry/node |
| Install Next.js |
bun add @sentry/nextjs @sentry/profiling-node |
| Install React |
bun add @sentry/react |
| Install CLI |
bun add -D @sentry/cli |
| Upload maps |
npx sentry-cli sourcemaps inject ./dist && npx sentry-cli sourcemaps upload ./dist |
| Setup wizard |
npx @sentry/wizard@latest -i sourcemaps |
| Test capture |
Sentry.captureMessage("Test from dev") |
Quick Reference
Capture Methods
| Method |
Purpose |
captureException(error) |
Capture error with stack trace |
captureMessage(msg) |
Capture text message |
captureCheckIn(opts) |
Cron job check-in |
addBreadcrumb(crumb) |
Add navigation/action trail |
Context Methods
| Method |
Purpose |
setTag(key, value) |
Add filterable tag |
setExtra(key, value) |
Add debug data |
setUser(user) |
Set user context |
withScope(callback) |
Scoped context |
Performance Methods
| Method |
Purpose |
startSpan(opts, callback) |
Create performance span |
withMonitor(slug, callback) |
Monitor cron job |
Severity Levels
| Level |
Use Case |
fatal |
App crash, unrecoverable |
error |
Error requiring attention |
warning |
Potential issue |
info |
Informational |
debug |
Debugging only |
Configuration Options
| Option |
Description |
dsn |
Project data source name |
environment |
Environment name (production, staging) |
release |
Application version |
tracesSampleRate |
Transaction sample rate (0.0-1.0) |
tracesSampler |
Dynamic sampling function |
sendDefaultPii |
Capture IP/headers |
integrations |
SDK integrations array |
enableLogs |
Forward structured logs to Sentry |
profileSessionSampleRate |
Profiling sample rate (0.0-1.0) |
profileLifecycle |
"trace" profiles every traced request |
replaysSessionSampleRate |
Session replay sample rate |
replaysOnErrorSampleRate |
Replay capture rate on errors |
ignoreErrors |
Array of error patterns to suppress |
beforeSend |
Filter/modify events before sending |
beforeSendTransaction |
Filter transactions before sending |
beforeSendLog |
Filter structured logs before sending |
For detailed examples, advanced patterns, and best practices, see REFERENCE.md.
1---
2name: typescript-sentry
3description: Error monitoring and performance with Sentry SDK for Bun/Node.js/Next.js — error capture, breadcrumbs, spans, cron monitoring, source maps, structured logging, profiling. Use when adding Sentry, instrumenting cron, or uploading sourcemaps.
4user-invocable: false
5allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TodoWrite
6created: 2026-01-22
7modified: 2026-07-28
8reviewed: 2026-01-22
9---
10
11# TypeScript Sentry
12
13This skill covers the **SDK-side** work: capture, spans, cron monitors, source maps, profiling, filtering. For project-level Sentry compliance (DSN hygiene, sourcemap-upload wiring in CI) use `/configure:sentry`; for local step-through debugging use `typescript-debugging`.
14
15## Core Expertise
16
17Sentry provides error monitoring and performance tracking:
18- Automatic error capture with stack traces
19- Performance monitoring with distributed tracing
20- Cron job monitoring for scheduled tasks
21- Source map integration for readable TypeScript traces
22- Rich context with tags, breadcrumbs, and user data
23- Structured logging forwarded to Sentry (`enableLogs`)
24- CPU/JS profiling (Node.js + browser)
25- Session replay with privacy controls
26- User feedback widget
27- Enrichment helpers (custom contexts, breadcrumb categories, fingerprinting)
28
29## Installation
30
31### Bun
32
33```bash
34bun add @sentry/bun
35```
36
37### Node.js
38
39```bash
40bun add @sentry/node
41```
42
43### Next.js
44
45```bash
46bun add @sentry/nextjs @sentry/profiling-node
47```
48
49### React/Browser
50
51```bash
52bun add @sentry/react
53# or
54bun add @sentry/browser
55```
56
57## Error Capturing
58
59### captureException
60
61```typescript
62try {
63 await riskyOperation();
64} catch (error) {
65 Sentry.captureException(error);
66 throw error; // Re-throw if needed
67}
68```
69
70### With Context
71
72```typescript
73Sentry.captureException(error, {
74 tags: {
75 feature: "checkout",
76 paymentProvider: "stripe",
77 },
78 extra: {
79 orderId: order.id,
80 userId: user.id,
81 cartItems: cart.items.length,
82 },
83 level: "error", // fatal, error, warning, info, debug
84});
85```
86
87### captureMessage
88
89```typescript
90// Simple message
91Sentry.captureMessage("User completed onboarding");
92
93// With level
94Sentry.captureMessage("Rate limit approaching", "warning");
95
96// With context
97Sentry.captureMessage("Payment failed", {
98 level: "error",
99 tags: { gateway: "stripe" },
100 extra: { errorCode: "card_declined" },
101});
102```
103
104## Agentic Optimizations
105
106| Context | Command |
107|---------|---------|
108| Install Bun | `bun add @sentry/bun` |
109| Install Node | `bun add @sentry/node` |
110| Install Next.js | `bun add @sentry/nextjs @sentry/profiling-node` |
111| Install React | `bun add @sentry/react` |
112| Install CLI | `bun add -D @sentry/cli` |
113| Upload maps | `npx sentry-cli sourcemaps inject ./dist && npx sentry-cli sourcemaps upload ./dist` |
114| Setup wizard | `npx @sentry/wizard@latest -i sourcemaps` |
115| Test capture | `Sentry.captureMessage("Test from dev")` |
116
117## Quick Reference
118
119### Capture Methods
120
121| Method | Purpose |
122|--------|---------|
123| `captureException(error)` | Capture error with stack trace |
124| `captureMessage(msg)` | Capture text message |
125| `captureCheckIn(opts)` | Cron job check-in |
126| `addBreadcrumb(crumb)` | Add navigation/action trail |
127
128### Context Methods
129
130| Method | Purpose |
131|--------|---------|
132| `setTag(key, value)` | Add filterable tag |
133| `setExtra(key, value)` | Add debug data |
134| `setUser(user)` | Set user context |
135| `withScope(callback)` | Scoped context |
136
137### Performance Methods
138
139| Method | Purpose |
140|--------|---------|
141| `startSpan(opts, callback)` | Create performance span |
142| `withMonitor(slug, callback)` | Monitor cron job |
143
144### Severity Levels
145
146| Level | Use Case |
147|-------|----------|
148| `fatal` | App crash, unrecoverable |
149| `error` | Error requiring attention |
150| `warning` | Potential issue |
151| `info` | Informational |
152| `debug` | Debugging only |
153
154### Configuration Options
155
156| Option | Description |
157|--------|-------------|
158| `dsn` | Project data source name |
159| `environment` | Environment name (production, staging) |
160| `release` | Application version |
161| `tracesSampleRate` | Transaction sample rate (0.0-1.0) |
162| `tracesSampler` | Dynamic sampling function |
163| `sendDefaultPii` | Capture IP/headers |
164| `integrations` | SDK integrations array |
165| `enableLogs` | Forward structured logs to Sentry |
166| `profileSessionSampleRate` | Profiling sample rate (0.0-1.0) |
167| `profileLifecycle` | `"trace"` profiles every traced request |
168| `replaysSessionSampleRate` | Session replay sample rate |
169| `replaysOnErrorSampleRate` | Replay capture rate on errors |
170| `ignoreErrors` | Array of error patterns to suppress |
171| `beforeSend` | Filter/modify events before sending |
172| `beforeSendTransaction` | Filter transactions before sending |
173| `beforeSendLog` | Filter structured logs before sending |
174
175For detailed examples, advanced patterns, and best practices, see [REFERENCE.md](REFERENCE.md).
laurigates