Skip to content

Commit 3db5cca

Browse files
lizhiyaolizhiyao
committed
feat: Add Mini Program SDK skill (sentry-miniapp)
Add a complete SDK setup wizard for mini programs using sentry-miniapp, a community SDK built on @sentry/core v10. Supports WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, Kuaishou mini programs and cross-platform frameworks (Taro / uni-app). Includes references for: - Error monitoring (automatic + manual capture) - Performance tracing (spans, distributed tracing, sessions) - Offline cache (weak network reliability) - Source map (stack trace resolution)
1 parent a0d5412 commit 3db5cca

5 files changed

Lines changed: 838 additions & 0 deletions

File tree

‎skills/sentry-miniapp-sdk/SKILL.md‎

Lines changed: 291 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,291 @@
1+
---
2+
name: sentry-miniapp-sdk
3+
description: Full Sentry setup wizard for Mini Programs — error monitoring, tracing, offline cache, source maps. Supports WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, Kuaishou and cross-platform frameworks (Taro / uni-app).
4+
license: Apache-2.0
5+
category: sdk-setup
6+
parent: sentry-sdk-setup
7+
disable-model-invocation: true
8+
---
9+
10+
> [All Skills](../../SKILL_TREE.md) > [SDK Setup](../sentry-sdk-setup/SKILL.md) > Mini Programs
11+
12+
# Sentry Mini Program SDK Setup
13+
14+
Set up Sentry error monitoring, performance tracing, and offline caching in mini program projects using [`sentry-miniapp`](https://github.com/lizhiyao/sentry-miniapp) — a community SDK built on `@sentry/core` v10.
15+
16+
## Invoke This Skill When
17+
18+
- User mentions **mini program**, **miniapp**, **小程序**, **WeChat**, **Alipay**, **ByteDance**, **Taro**, **uni-app** alongside Sentry
19+
- User wants to add error monitoring or performance tracking to a mini program
20+
- User asks about Sentry support for WeChat/Alipay/ByteDance mini programs
21+
- User imports or references `sentry-miniapp` in their project
22+
23+
> **Note:** SDK versions and APIs reflect the current sentry-miniapp docs. Always verify against the [sentry-miniapp README](https://github.com/lizhiyao/sentry-miniapp) before implementing.
24+
25+
---
26+
27+
## Phase 1: Detect
28+
29+
Run these commands to understand the project:
30+
31+
```bash
32+
# Detect mini program platform
33+
ls app.json project.config.json mini.project.json 2>/dev/null
34+
cat app.json 2>/dev/null | head -20
35+
36+
# Detect framework (Taro / uni-app / native)
37+
cat package.json 2>/dev/null | grep -E '"@tarojs/|"@dcloudio/uni-|"sentry-miniapp"'
38+
39+
# Check for existing Sentry SDK
40+
grep -r "sentry" package.json 2>/dev/null
41+
grep -r "Sentry.init" app.js app.ts src/app.js src/app.ts 2>/dev/null
42+
43+
# Detect entry point
44+
ls app.js app.ts src/app.js src/app.ts 2>/dev/null
45+
46+
# Detect package manager
47+
ls yarn.lock pnpm-lock.yaml package-lock.json 2>/dev/null
48+
```
49+
50+
**What to determine:**
51+
52+
| Question | Impact |
53+
|----------|--------|
54+
| Which mini program platform? | Determines `platform` option and API differences |
55+
| Native or cross-platform framework (Taro/uni-app)? | Determines init pattern and build config |
56+
| Is `sentry-miniapp` already installed? | Skip install if present, check version |
57+
| Where is the app entry point? | Determines where to place `Sentry.init()` |
58+
| Is there a build tool config (webpack/vite)? | Needed for Source Map setup |
59+
60+
### Platform Detection Guide
61+
62+
| File Present | Platform |
63+
|-------------|----------|
64+
| `project.config.json` | WeChat (微信) |
65+
| `mini.project.json` | Alipay (支付宝) |
66+
| `project.tt.json` | ByteDance (字节跳动) |
67+
| `project.swan.json` | Baidu (百度) |
68+
| `project.qq.json` | QQ |
69+
| `@tarojs/*` in package.json | Taro (cross-platform) |
70+
| `@dcloudio/uni-*` in package.json | uni-app (cross-platform) |
71+
72+
---
73+
74+
## Phase 2: Recommend
75+
76+
Present this recommendation based on detection results:
77+
78+
**Recommended (core coverage):**
79+
80+
- ✅ **Error Monitoring** — always. Automatic capture of `onError`, `onUnhandledRejection`, `onPageNotFound`, `onMemoryWarning`
81+
- ✅ **Performance Tracing** — always. Navigation timing, render performance, resource loading, custom spans
82+
83+
**Recommended for production:**
84+
85+
- ⚡ **Source Map Upload** — when deploying to production. Maps minified stack traces back to source code
86+
- ⚡ **Offline Cache** — when users are on unreliable networks. Caches events locally, retries when connectivity returns
87+
88+
**Optional:**
89+
90+
- ⚡ **Distributed Tracing** — when mini program calls backend APIs. Injects `sentry-trace`/`baggage` headers to link frontend and backend spans
91+
- ⚡ **User Feedback** — when you want to collect user-reported issues via `Sentry.captureFeedback()`
92+
93+
| Feature | Recommend when... |
94+
|---------|-------------------|
95+
| Error Monitoring | **Always** — zero-config automatic exception capture |
96+
| Performance Tracing | **Always** — automatic page/network/render performance |
97+
| Source Map | **Production** — required to read minified stack traces |
98+
| Offline Cache | **Weak networks** — mobile users, rural areas |
99+
| Distributed Tracing | **API calls** — mini program talks to backend services |
100+
| User Feedback | **User-facing** — collect bug reports from end users |
101+
102+
---
103+
104+
## Phase 3: Guide
105+
106+
### Step 1: Install
107+
108+
```bash
109+
# npm
110+
npm install sentry-miniapp
111+
112+
# yarn
113+
yarn add sentry-miniapp
114+
```
115+
116+
### Step 2: Initialize
117+
118+
Create or modify the app entry point. `Sentry.init()` **must** be called **before** `App()`.
119+
120+
#### Native Mini Program (app.js)
121+
122+
```javascript
123+
const Sentry = require('sentry-miniapp');
124+
125+
Sentry.init({
126+
dsn: 'https://<key>@<org>.ingest.sentry.io/<project>',
127+
release: 'my-miniapp@1.0.0',
128+
environment: 'production',
129+
});
130+
131+
App({
132+
// Your app config...
133+
// No need to manually call Sentry in onError — SDK handles it automatically
134+
});
135+
```
136+
137+
#### Taro (app.js or app.ts)
138+
139+
```typescript
140+
import * as Sentry from 'sentry-miniapp';
141+
142+
Sentry.init({
143+
dsn: 'https://<key>@<org>.ingest.sentry.io/<project>',
144+
release: 'my-miniapp@1.0.0',
145+
environment: 'production',
146+
});
147+
148+
// Taro App component follows...
149+
```
150+
151+
#### uni-app (App.vue or main.js)
152+
153+
```javascript
154+
const Sentry = require('sentry-miniapp');
155+
156+
Sentry.init({
157+
dsn: 'https://<key>@<org>.ingest.sentry.io/<project>',
158+
release: 'my-miniapp@1.0.0',
159+
environment: 'production',
160+
});
161+
```
162+
163+
### Step 3: Configure Platform (if needed)
164+
165+
The SDK auto-detects the platform at runtime. No explicit `platform` option is required in most cases.
166+
167+
If you need to force a specific platform:
168+
169+
```javascript
170+
Sentry.init({
171+
dsn: '...',
172+
platform: 'wechat', // 'wechat' | 'alipay' | 'bytedance' | 'qq' | 'baidu' | 'dingtalk'
173+
});
174+
```
175+
176+
### Step 4: Add User Context
177+
178+
```javascript
179+
// After user login
180+
Sentry.setUser({
181+
id: 'user-123',
182+
username: 'zhang_san',
183+
});
184+
185+
// Add custom tags
186+
Sentry.setTag('page', 'payment');
187+
Sentry.setContext('order', { orderId: '2024001', amount: 99.9 });
188+
```
189+
190+
### For Each Agreed Feature
191+
192+
Walk through features one at a time. Load the corresponding reference file:
193+
194+
| Feature | Reference | Load when... |
195+
|---------|-----------|-------------|
196+
| Error Monitoring | `${SKILL_ROOT}/references/error-monitoring.md` | Always |
197+
| Performance Tracing | `${SKILL_ROOT}/references/tracing.md` | User agreed to tracing |
198+
| Offline Cache | `${SKILL_ROOT}/references/offline-cache.md` | User agreed to offline cache |
199+
| Source Map | `${SKILL_ROOT}/references/sourcemap.md` | User agreed to source maps |
200+
201+
---
202+
203+
## Configuration Reference
204+
205+
### Key Init Options
206+
207+
| Option | Type | Default | Description |
208+
|--------|------|---------|-------------|
209+
| `dsn` | `string` | — | Sentry DSN (required) |
210+
| `release` | `string` | — | Release version, must match source map upload |
211+
| `environment` | `string` | — | Environment name (production, staging, etc.) |
212+
| `sampleRate` | `number` | `1.0` | Error event sample rate (0.0–1.0) |
213+
| `tracesSampleRate` | `number` | — | Trace sample rate (0.0–1.0) |
214+
| `tracesSampler` | `function` | — | Dynamic sampling function (overrides tracesSampleRate) |
215+
| `enableSourceMap` | `boolean` | `true` | Auto-normalize stack trace paths for source map resolution |
216+
| `enableOfflineCache` | `boolean` | `true` | Cache events when offline, retry when back online |
217+
| `offlineCacheLimit` | `number` | `30` | Max events to store in offline cache |
218+
| `enableTracePropagation` | `boolean` | `true` | Inject sentry-trace/baggage headers in outgoing requests |
219+
| `tracePropagationTargets` | `Array` | `[]` | URL patterns for trace header injection (empty = all) |
220+
| `enableAutoSessionTracking` | `boolean` | `true` | Automatic session lifecycle management |
221+
| `enableConsoleBreadcrumbs` | `boolean` | `false` | Capture console.log/warn/error as breadcrumbs |
222+
| `beforeSend` | `function` | — | Event processor for filtering/modifying events |
223+
224+
### Platform Compatibility
225+
226+
| Feature | WeChat | Alipay | ByteDance | Baidu | QQ | DingTalk | Kuaishou |
227+
|---------|--------|--------|-----------|-------|----|----------|----------|
228+
| Error Capture | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
229+
| Performance | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
230+
| Offline Cache | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
231+
| Distributed Tracing | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
232+
| Session Tracking | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
233+
| Source Map | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
234+
235+
---
236+
237+
## Verification
238+
239+
After setup, verify the integration:
240+
241+
1. **Trigger a test error:**
242+
243+
```javascript
244+
// In any page
245+
Sentry.captureException(new Error('Test error from mini program'));
246+
```
247+
248+
2. **Check Sentry dashboard:**
249+
- Go to your Sentry project → Issues
250+
- You should see the test error with:
251+
- Device info (brand, model, OS)
252+
- Mini program context (platform, SDK version)
253+
- Breadcrumbs (page navigation, network requests)
254+
255+
3. **Verify automatic capture works:**
256+
- Throw an unhandled error in a page — it should appear in Sentry without any manual `captureException` call
257+
258+
---
259+
260+
## Phase 4: Cross-Link
261+
262+
After mini program setup, check for companion services:
263+
264+
```bash
265+
# Check for backend services in the same workspace
266+
ls -d ../*/package.json ../*/requirements.txt ../*/go.mod ../*/Gemfile 2>/dev/null
267+
```
268+
269+
| Backend Detected | Suggest |
270+
|-----------------|---------|
271+
| Node.js (`package.json` with server framework) | `sentry-node-sdk` skill |
272+
| Python (`requirements.txt`) | `sentry-python-sdk` skill |
273+
| Go (`go.mod`) | `sentry-go-sdk` skill |
274+
| Ruby (`Gemfile`) | `sentry-ruby-sdk` skill |
275+
| Java (`pom.xml` / `build.gradle`) | Sentry Java SDK docs |
276+
277+
> **Tip:** Enable distributed tracing on both mini program and backend to get end-to-end request traces across services.
278+
279+
---
280+
281+
## Troubleshooting
282+
283+
| Issue | Solution |
284+
|-------|----------|
285+
| Events not appearing in Sentry | Check DSN is correct; verify Sentry domain is in mini program's trusted domain list |
286+
| `sampleRate` filtering all events | Ensure `sampleRate` is not set to `0`; default is `1.0` |
287+
| Minified stack traces | Set up Source Map upload — see `${SKILL_ROOT}/references/sourcemap.md` |
288+
| Duplicate error reports | Do NOT manually call `Sentry.captureException` in `onError` — SDK captures automatically |
289+
| Events lost on weak networks | Enable offline cache: `enableOfflineCache: true` (default) |
290+
| WeChat DevTools not triggering `onError` | Test on a real device; DevTools may not trigger all error handlers |
291+
| Stack trace paths don't match source maps | Ensure `--url-prefix "app:///"` when uploading; SDK normalizes paths to `app:///` automatically |

0 commit comments

Comments
 (0)