sentry-miniapp 1.11.2 → 1.12.0

package/README.en.md

@@ -11,25 +11,27 @@
 
 [简体中文](./README.md) | English
 
-> **📖 Documentation**: [https://sentry-miniapp.pages.dev/](https://sentry-miniapp.pages.dev/) — getting started, capability matrix, FAQ, Source Map setup, and examples, with nav and search. (Chinese for now)
-
 A **mini program monitoring SDK** built on `@sentry/core`, providing **error monitoring**, **performance monitoring**, offline caching, and distributed tracing. Supports WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, Kuaishou mini programs, **WeChat / Douyin mini games**, and cross-platform frameworks (Taro / uni-app).
 
-> **What are Mini Programs?** Mini programs (小程序) are lightweight apps that run inside super-apps like WeChat, Alipay, and ByteDance/Douyin. They form a massive ecosystem in China with **hundreds of millions of daily active users**, but have no direct equivalent in the Western tech stack. Think of them as a hybrid between PWAs and native apps, but hosted within a platform's sandbox.
+> **What are Mini Programs?** Mini programs (小程序) are lightweight apps that run inside super-apps like WeChat, Alipay, and ByteDance/Douyin. They form a massive ecosystem in China with **hundreds of millions of daily active users**, but have no direct equivalent in the Western stack — think of them as a hybrid of PWAs and native apps, hosted within a platform's sandbox.
+
+> **📖 Full docs live on the documentation site**: [sentry-miniapp.pages.dev](https://sentry-miniapp.pages.dev/) — getting started, capability matrix, per-framework setup, FAQ, Source Map config, and examples, with nav and search (Chinese for now). This README is a quick overview and entry point.
 
 > **📰 Featured Article (Chinese)**: [《我给 Sentry 提了个 PR，后来 sentry-miniapp 进了官方文档》](https://juejin.cn/post/7636106283963760681) — How sentry-miniapp got listed in Sentry's official community-supported SDKs documentation. If you find this project useful, please consider giving it a ⭐ Star.
 
 <details>
-<summary><b>🆕 What's New: v1.3 → v1.8 (click to expand)</b></summary>
+<summary><b>🆕 What's New: v1.3 → v1.11 (click to expand)</b></summary>
 
 | Version | Highlights |
 |---|---|
+| **v1.11** | Mini-game performance data reported as **independent transactions** (Sentry Performance page); API requests reported as `http.client` spans; launched the [documentation site](https://sentry-miniapp.pages.dev/), added Taro / uni-app examples and a [two-layer Source Map merge script](./scripts/merge-sourcemap.mjs) |
+| **v1.10** | 🎮 **Mini game support**: auto-detects mini-game environments; adds cold-start first-frame timing and frame-rate / jank (FPS) monitoring |
 | **v1.8.0** | AI-assisted integration skill — auto onboarding via Claude Code / Cursor |
 | **v1.7.0** | New `tracesSampler` for dynamic sampling; complete Source Map configuration guide |
-| **v1.6.0** | 13 enhancements + 16 fixes; enabled esbuild minification — bundle size reduced by ~**59%** |
-| **v1.5.0** | Performance enhancements (configurable thresholds / slow `setData` detection / memory sampling); new page lifecycle, user interaction, and Console breadcrumbs; route integration covers all platforms |
-| **v1.4.0** | `NetworkBreadcrumbs` captures Request / Response body; configurable offline cache limit; deprecated `showReportDialog` in favor of `captureFeedback` |
-| **v1.3.0** | 🎯 Build pipeline rewrite (Vite + bundle-inline): **zero external deps**, fully resolves the `miniprogram_npm` module-resolution issue; 🎯 built-in Source Map path normalization across all platforms |
+| **v1.6.0** | 13 enhancements + 16 fixes; build output minification — bundle size reduced by ~**59%** |
+| **v1.5.0** | Performance enhancements (configurable thresholds / slow `setData` detection / memory sampling); new page lifecycle, user interaction, and Console breadcrumbs |
+| **v1.4.0** | `NetworkBreadcrumbs` captures Request / Response body; configurable offline cache limit |
+| **v1.3.0** | 🎯 Build pipeline rewrite (Vite + bundle-inline): **zero external deps**, resolves the `miniprogram_npm` module-resolution issue; built-in Source Map path normalization |
 
 See [CHANGELOG.md](./CHANGELOG.md) for full details.
 
@@ -37,472 +39,163 @@ See [CHANGELOG.md](./CHANGELOG.md) for full details.
 
 ---
 
-## Core Features
-
-- **Modern Architecture**: Built on the latest Sentry JavaScript V10 SDK core modules.
-- **True Multi-Platform Support**: Built-in API abstraction engine — one codebase seamlessly supports **WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, and Kuaishou** mini program platforms.
-- **Mini Game Support**: Auto-detects mini-game environments — error / network / device monitoring works out of the box, plus mini-game-specific **cold-start first-frame timing** and **frame-rate / jank (FPS) monitoring** (see "Mini Game Support" below).
-- **Automatic Exception Capture**: No business code intrusion required. Automatically hooks into lifecycle error listeners (`onError`, `onUnhandledRejection`, `onPageNotFound`, `onMemoryWarning`).
-- **Rich Context Breadcrumbs**: Automatically records device info, user tap/touch interactions, network requests (XHR/Fetch), and page lifecycle events.
-- **Built-in SourceMap Path Normalization**: Handles virtual stack paths across WeChat, Alipay, ByteDance and other platforms. Works with sentry-cli for seamless SourceMap resolution.
-- **Offline Caching for Weak Networks**: Designed for mini program network conditions. Automatically caches events to local storage on network failure, silently retries when connectivity is restored.
-- **Deep Performance Monitoring**: Integrates mini program Performance API for navigation timing (FCP/LCP), render performance, resource loading, and custom performance marks.
-- **Smart Deduplication & Filtering**: Built-in error deduplication and sample rate controls to prevent log storms.
-- **Cross-Platform Framework Friendly**: Works seamlessly with Taro, uni-app, and other cross-platform compilation frameworks.
-- **Distributed Tracing**: Automatically injects `sentry-trace` / `baggage` headers into network requests and reports mini program API timing as `http.client` spans, connecting mini program and backend service call chains.
-- **Session Health Monitoring**: Automatic session lifecycle management with crash rate and session health data in the Sentry Release Health dashboard.
-- **Network Status Monitoring**: Real-time tracking of network changes (WiFi/4G/offline) to help diagnose network-related exceptions.
-- **Stack Trace Parsing**: Built-in multi-platform stack parser supporting V8/Safari/JavaScriptCore formats for precise error location with SourceMap.
+## ✨ Core Features
+
+- **🚀 Modern Architecture**: Built on the latest Sentry JavaScript V10 SDK core modules.
+- **📱 True Multi-Platform Support**: Built-in API abstraction engine — one codebase supports **WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, and Kuaishou** mini programs.
+- **🎮 Mini Game Support**: Auto-detects mini-game environments — error / network / device monitoring out of the box, plus mini-game-specific **cold-start first-frame timing** and **frame-rate / jank monitoring**.
+- **🎯 Automatic Exception Capture**: No business code intrusion. Hooks into lifecycle error listeners (`onError`, `onUnhandledRejection`, `onPageNotFound`, `onMemoryWarning`).
+- **🍞 Rich Context Breadcrumbs**: Auto-records device info, user tap/touch, network requests (XHR), and page lifecycle.
+- **🗺️ Built-in SourceMap Path Normalization**: Unifies virtual stack paths across platforms; works with sentry-cli for seamless resolution.
+- **📡 Offline Caching for Weak Networks**: Caches events to local storage on failure, silently retries when connectivity returns.
+- **⚡ Deep Performance Monitoring**: Navigation timing (FCP/LCP), render performance, resource loading, and custom marks.
+- **🔗 Distributed Tracing**: Injects `sentry-trace` / `baggage` headers and reports API timing as `http.client` spans, connecting mini program and backend call chains.
+- **📊 Session Health** & **📶 Network Status Monitoring**: Session lifecycle management + real-time network change tracking (WiFi/4G/offline).
+- **🛡️ Smart Deduplication & Filtering**: Built-in dedup and sample rate controls to prevent log storms.
 
 ---
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install sentry-miniapp
 ```
 
-*Tip: If you don't use npm, you can also copy `examples/wxapp/lib/sentry-miniapp.js` from this repository directly into your mini program project.*
+> Not using npm? Copy `examples/wxapp/lib/sentry-miniapp.js` from this repo directly into your project.
 
----
+### 🤖 AI-Assisted Setup
 
-## AI-Assisted Setup
-
-If you use [Claude Code](https://claude.ai/code) or [Cursor](https://cursor.com), get AI-guided setup with one command:
+With [Claude Code](https://claude.ai/code) or [Cursor](https://cursor.com), get AI-guided setup:
 
 ```bash
 npx skills add https://github.com/lizhiyao/sentry-miniapp --skill sentry-miniapp-sdk
 ```
 
-After installation, just ask "help me set up Sentry monitoring" in your AI editor.
+Then just ask "help me set up Sentry monitoring" in your AI editor.
 
 ---
 
-## Quick Start
-
-### 1. Prerequisites
-
-1. Ensure you have a Sentry account ([Sentry SaaS](https://sentry.io/) or self-hosted).
-2. **Important**: Add your Sentry reporting endpoint domain to the `request` trusted domain list in your mini program platform's admin console.
+## 🚀 Quick Start
 
-### 2. Initialize the SDK
+**Prerequisites**: ① a Sentry account ([SaaS](https://sentry.io/) or self-hosted); ② add your Sentry endpoint domain to the `request` trusted-domain list in your mini program console.
 
-Initialize Sentry at the **top** of your mini program entry file (e.g., `app.js` or `app.ts`), **before** calling `App()`.
+Initialize at the **top** of your entry file (`app.js` / `app.ts`), **before** `App()`:
 
 ```javascript
 import * as Sentry from 'sentry-miniapp';
 
 Sentry.init({
   dsn: 'https://<key>@sentry.io/<project>',
+  release: 'my-project@1.0.0', // match the release you upload Source Maps with
   environment: 'production',
-  release: 'my-project-name@1.0.0',
-
-  // --- Mini Program Configuration ---
-  platform: 'wechat', // Optional event platform label; runtime platform is auto-detected
-  enableUserInteractionBreadcrumbs: true, // Auto-record user tap events
-  enableConsoleBreadcrumbs: false, // Record console output as breadcrumbs (default: false)
-  traceNetworkBody: false, // Record request/response bodies in breadcrumbs (default: false)
-
-  // --- Offline Cache & Reliability ---
-  enableOfflineCache: true, // Enable offline caching with retry (default: true)
-  offlineCacheLimit: 30, // Max cached events (default: 30)
-
-  // --- SourceMap Support ---
-  enableSourceMap: true, // Normalize virtual stack paths for SourceMap resolution
-
-  // --- Sampling ---
-  sampleRate: 1.0, // Error reporting sample rate (0.0 - 1.0)
-  tracesSampleRate: 1.0, // Performance tracing sample rate; API requests are reported as http.client spans
-
-  // --- Distributed Tracing ---
-  enableTracePropagation: true, // Auto-inject sentry-trace/baggage headers (default: true)
-  tracePropagationTargets: ['api.example.com'], // Only inject tracing headers for specified domains; spans still follow tracing sampling
-
-  // --- Session & Network Monitoring ---
-  enableAutoSessionTracking: true, // Auto session lifecycle management (default: true)
-  enableNetworkStatusMonitoring: true, // Real-time network status monitoring (default: true)
+  sampleRate: 1.0, // error sample rate
+  tracesSampleRate: 1.0, // performance sample rate; API requests become http.client spans
 });
 
-App({
-  onLaunch() {
-    // ...
-  }
-});
+App({ onLaunch() {} });
 ```
 
-Default integrations already include automatic exception capture, performance monitoring, SourceMap path normalization, network breadcrumbs, session tracking, and network status monitoring. Only pass `integrations` when you intentionally want to take over the full integration list, because it replaces the defaults.
+Do not put `Sentry.init` inside `App.onLaunch`: by then `App()` has already been registered, so the SDK cannot wrap that first `onLaunch` call. App lifecycle breadcrumbs, the first session start, and cold-start timing which depends on the `onLaunch` start point may be missing. If you only need later errors, network breadcrumbs, and manual capture, initializing in `onLaunch` still works, but startup instrumentation is degraded.
 
----
-
-## Advanced Usage
+Default integrations already include **exception capture, performance monitoring, Source Map path normalization, network breadcrumbs, session and network status monitoring** — you usually don't pass `integrations` (doing so replaces the defaults). Full options (offline cache, trace propagation, breadcrumb toggles) are on the [docs site · Configuration](https://sentry-miniapp.pages.dev/guide/configuration).
 
-After initialization, the SDK works automatically in the background. You can also use the following APIs for manual instrumentation.
-
-### Manual Exception & Message Reporting
+**Verify it works** — capture an event and check the Sentry "Issues" list:
 
 ```javascript
-// Manually capture and report an Error
-try {
-  throw new Error('Payment API parsing failed');
-} catch (error) {
-  Sentry.captureException(error);
-}
-
-// Log a message
-Sentry.captureMessage('User cancelled authorization', 'info');
+Sentry.captureException(new Error('sentry test'));
 ```
 
-### Context Enrichment (Context & Breadcrumbs)
-
-```javascript
-// Set current user info
-Sentry.setUser({
-  id: 'user_12345',
-  username: 'John Doe'
-});
-
-// Set global tags for filtering and analytics
-Sentry.setTag('page_module', 'checkout_counter');
+> ⚠️ `addBreadcrumb` is not reported on its own — it only ships with the next event. Calling it without capturing an event leaves your dashboard empty.
 
-// Manually add a breadcrumb
-Sentry.addBreadcrumb({
-  message: 'User tapped [Confirm Payment] button',
-  category: 'action',
-  level: 'info',
-  data: { cartId: 'c_888' }
-});
-```
+---
 
-### Custom Performance Measurement
+## 📚 Common APIs
 
 ```javascript
-await Sentry.startSpan(
-  {
-    name: 'fetch-user-data',
-    op: 'http.client',
-  },
-  async () => {
-    await fetchUserData();
-  },
-);
-```
+// Manual capture
+Sentry.captureException(new Error('Payment API parsing failed'));
+Sentry.captureMessage('User cancelled authorization', 'info');
 
-### Dynamic Sampling (tracesSampler)
+// User & tags
+Sentry.setUser({ id: 'user_12345', username: 'John Doe' });
+Sentry.setTag('page_module', 'checkout');
 
-Beyond the global `sampleRate`, you can use the `tracesSampler` callback for fine-grained, per-page sampling control:
+// Breadcrumb
+Sentry.addBreadcrumb({ message: 'Tapped [Confirm Payment]', category: 'action', level: 'info' });
 
-```javascript
-Sentry.init({
-  dsn: '...',
-  tracesSampler: ({ name, inheritOrSampleWith }) => {
-    // 100% sampling for critical pages
-    if (name.includes('pages/index') || name.includes('pages/pay')) {
-      return 1;
-    }
-    // Lower sampling for low-priority pages
-    if (name.includes('pages/about') || name.includes('pages/settings')) {
-      return 0.1;
-    }
-    // Inherit upstream decision or fall back to 50%
-    return inheritOrSampleWith(0.5);
-  },
-});
+// Custom span
+await Sentry.startSpan({ name: 'fetch-user', op: 'http.client' }, async () => { /* ... */ });
 ```
 
-> **Note:** When `tracesSampler` is set, `tracesSampleRate` is ignored. `tracesSampler` takes priority.
+For per-page / per-scenario sampling use the `tracesSampler` callback (it overrides `tracesSampleRate`); see the [docs site · Configuration](https://sentry-miniapp.pages.dev/guide/configuration).
 
 ---
 
-## SourceMap Support
+## 🗺️ Source Map
 
-The SDK includes built-in multi-platform stack path normalization (`enableSourceMap: true`, enabled by default), automatically converting platform-specific virtual paths to the `app:///` prefix for seamless SourceMap resolution with sentry-cli.
-
-**Quick upload example:**
+The SDK normalizes platform virtual stack paths to the `app:///` prefix by default (`enableSourceMap: true`). Upload with sentry-cli:
 
 ```bash
 sentry-cli releases files "my-miniapp@1.0.0" upload-sourcemaps ./dist \
-  --url-prefix "app:///" \
-  --ext js --ext map
+  --url-prefix "app:///" --ext js --ext map
 ```
 
-> For a complete end-to-end setup guide (build tool configs, CI/CD integration, verification & troubleshooting), see **[Source Map Configuration Guide](./docs/SOURCEMAP_GUIDE.md)**.
+> Full end-to-end setup (build tools, CI/CD, two-layer map merging for cross-platform frameworks, verification) is in the **[Source Map Configuration Guide](./docs/SOURCEMAP_GUIDE.md)**.
 
 ---
 
-## User Feedback
-
-In web environments, Sentry provides a built-in `showReportDialog()` popup. However, mini programs have no DOM, so this method is **not available**.
-
-Instead, build a **native mini program form or modal** to collect user feedback, then submit it via `Sentry.captureFeedback()`:
-
-```javascript
-const userMessage = 'The page is frozen, nothing responds';
-const userName = 'John Doe';
-const userEmail = 'john@example.com';
-
-Sentry.captureFeedback({
-  message: userMessage,
-  name: userName,
-  email: userEmail,
-  // Optional: associate with a specific error event
-  // associatedEventId: 'abc123xyz...'
-});
-```
-
----
+## 🎮 Mini Game Support
 
-## Bundle Size Optimization (Zero Main Package Overhead)
+`sentry-miniapp` also works in WeChat / Douyin **mini games**: auto-detects the environment, error / network / device monitoring out of the box, plus **cold-start first-frame timing** and **frame-rate / jank monitoring**. Initialization is identical to mini programs; with `tracesSampleRate` enabled, performance data is reported as independent transactions on the Performance page.
 
-Mini program "main package" size is limited (typically 2MB). `sentry-miniapp` includes the full `@sentry/core` engine and multi-platform adapters, totaling ~100KB.
+> Capability matrix and performance-reporting details: [docs site · Platforms & Capabilities](https://sentry-miniapp.pages.dev/guide/platforms).
 
-If main package size is a concern, use **subpackage async loading** or **dynamic loading** to move the SDK entirely into a subpackage.
+## 📦 Bundle Size Optimization
 
-### Option A: WeChat / Alipay (Recommended)
+The SDK is ~100KB. If main-package size matters, use platform "subpackage async" / "dynamic loading" to move the SDK into a subpackage and reduce main-package overhead; platforms with cross-subpackage async loading can reach zero main-package overhead.
 
-WeChat and Alipay natively support [subpackage async loading](https://developers.weixin.qq.com/miniprogram/dev/framework/subpackages/async.html).
-
-```javascript
-// app.js
-App({
-  onLaunch() {
-    require.async('./subpackageA/sentry-miniapp.js').then((Sentry) => {
-      Sentry.init({
-        dsn: 'https://xxxxxxxx@sentry.io/12345',
-        // ...other options
-      });
-      console.log('Sentry loaded and initialized successfully');
-    }).catch(err => {
-      console.error('Failed to load Sentry', err);
-    });
-  }
-});
-```
-
-*This way, Sentry's ~100KB is counted against `subpackageA`'s size — zero main package overhead!*
-
-### Option B: Other Platforms (ByteDance, Baidu, etc.)
-
-For platforms that don't support `require.async`, use **subpackage predownload + dynamic loading**:
-
-```javascript
-// ByteDance mini program example
-App({
-  onLaunch() {
-    const loadTask = tt.loadSubpackage({
-      name: 'subpackageA',
-      success: () => {
-        const Sentry = require('./subpackageA/sentry-miniapp.js');
-        Sentry.init({ dsn: '...' });
-      }
-    });
-  }
-});
-```
-
-*Note: If using Taro / uni-app, you can use `import('sentry-miniapp')` dynamic import syntax — the framework handles cross-platform differences at compile time.*
+> WeChat subpackage async loading and cross-platform verification guidance: [docs site · Bundle Size](https://sentry-miniapp.pages.dev/guide/bundle-size).
 
 ---
 
-## Mini Game Support
-
-`sentry-miniapp` also works in **mini games** (WeChat / ByteDance mini games, etc.). Mini games have no `App()`/`Page()`/page routing, but expose platform APIs like `wx.onError`, `wx.request`, `wx.getDeviceInfo`, and `wx.getPerformance`. Most SDK capabilities work out of the box, plus mini-game-specific cold-start and frame-rate monitoring.
-
-**Initialization is identical to mini programs** — the SDK auto-detects the mini-game environment and enables the relevant features:
-
-```js
-import * as Sentry from 'sentry-miniapp';
-
-Sentry.init({
-  dsn: 'YOUR_DSN',
-  // Enabled by default in mini-game environments; set to false to disable:
-  // enableMinigameLifecycle: true,  // cold-start first-frame timing + launch scene + onShow/onHide breadcrumbs
-  // enableMinigameFrameRate: true,  // FPS / jank monitoring
-
-  // Fine-tune frame-rate monitoring (FPS warning threshold, jank threshold, report interval, etc.):
-  // minigameFrameRateOptions: { fpsWarningThreshold: 45 },
-});
-```
-
-### Capability matrix
-
-| Capability | Mini Game | Notes |
-|------------|:---------:|-------|
-| Exception / unhandled rejection capture | ✅ | `wx.onError` / `wx.onUnhandledRejection` |
-| API request monitoring (count / duration / status) | ✅ | wraps `wx.request`; creates `http.client` spans when tracing is enabled |
-| Network status monitoring | ✅ | `wx.onNetworkStatusChange` |
-| Device info / context breadcrumbs | ✅ | `wx.getDeviceInfo` etc. |
-| Resource load timing | ✅ | `wx.getPerformance()` |
-| **Cold-start first-frame timing + launch scene** | ✅ New | `MinigameIntegration` (first `requestAnimationFrame` ≈ first frame) |
-| **Frame rate / jank monitoring** | ✅ New | `MinigameFrameRateIntegration` (RAF FPS sampling, long frames → jank, periodic `minigame.framerate` context) |
-| Page lifecycle / tap breadcrumbs | ➖ | No pages in mini games — auto-skipped; use `onShow/onHide` breadcrumbs or manual `addBreadcrumb` |
+## 💬 User Feedback
 
-> These two integrations are enabled by default only in mini-game environments. In particular, **frame-rate monitoring relies on a global `requestAnimationFrame`**: mini games have one (bound to the real render loop), whereas mini programs use a dual-thread architecture whose logic layer has no global `requestAnimationFrame` — so even if enabled there, it safely no-ops (it cannot measure page render frame rate).
+Mini programs have no DOM, so `showReportDialog()` is deprecated. Build a native form to collect feedback, then submit via `Sentry.captureFeedback()`:
 
-#### Independent performance reporting (Performance page)
-
-Cold-start and frame-rate data are **not only attached to error events** — with tracing enabled they are reported as independent transactions, so you can aggregate trends / distributions / P95 across sessions on the Sentry Performance page:
-
-- **Cold start** → a `minigame.coldstart` transaction (with a `cold_start` measurement).
-- **Frame rate / jank** → accumulated per session and flushed as a single `minigame.framerate.summary` transaction on **background (onHide) / session end** (with `fps_avg` / `fps_p95` / `fps_min` / `jank_count` measurements) — no per-window events, quota-friendly.
-
-```js
-Sentry.init({
-  dsn: 'YOUR_DSN',
-  tracesSampleRate: 1.0, // enable performance sampling (decoupled from error sampleRate)
-});
+```javascript
+Sentry.captureFeedback({ message: 'The page is frozen', name: 'John Doe', email: 'john@example.com' });
 ```
 
-> Requires `tracesSampleRate` (or `tracesSampler`) for performance transactions to be sent; this sampling is **independent of** the error `sampleRate`. Without tracing enabled, it degrades to the original behavior: performance data is only attached to error events as `minigame` / `minigame.framerate` contexts + breadcrumbs.
-
 ---
 
-## FAQ
+## ❓ FAQ (quick reference)
 
-### 1. Do I need to manually report errors in `onError`?
+- **Must I report manually in `onError`?** No — `init` hooks the global error listeners automatically.
+- **Are network requests included with errors?** Yes, on by default — recorded as `category: xhr` breadcrumbs shipped with the error.
+- **uni-app (Vue) component errors rarely reported?** Vue swallows component errors; wire `app.config.errorHandler`. Taro (React) uses an Error Boundary.
+- **Session Replay?** Not supported (no DOM); reconstruct via breadcrumbs.
+- **H5 build?** Use official `@sentry/browser`, branched via conditional compilation.
 
-**No.** `sentry-miniapp` automatically hooks into platform-level global error listeners (e.g., `wx.onError`) during initialization. As long as `Sentry.init` is called **before** `App()`, it captures all unhandled JS exceptions automatically.
-
-If errors are not being reported, check:
-1. Whether the Sentry domain is in the mini program's trusted domain list.
-2. Whether `sampleRate` is set too low.
-3. Some WeChat DevTools environments don't trigger `onError` — test on a **real device**.
-
-### 2. Does this SDK support Session Replay?
-
-**Not currently.** Sentry's official Replay feature relies on standard browser DOM (via rrweb recording). Mini programs use a dual-thread architecture without standard DOM access. We recommend using **Breadcrumbs** combined with **custom logging** to reconstruct user action sequences.
-
-### 3. How do I monitor the H5 build of a uni-app / Taro project?
-
-`sentry-miniapp` **only adapts mini program platforms** and does not implement browser-native signals (`window.onerror`, `fetch` / `XHR` interception, `PerformanceObserver`, etc.). For the H5 build, use Sentry's official [`@sentry/browser`](https://docs.sentry.io/platforms/javascript/) directly — full feature coverage, maintained upstream.
-
-> When this SDK is initialized in a browser environment, it logs a warning suggesting you switch to `@sentry/browser`.
-
-Recommended pattern: split SDKs by platform via **uni-app conditional compilation**:
-
-```ts
-// utils/sentry.ts
-let Sentry: any;
-
-// #ifdef H5
-Sentry = require('@sentry/browser');
-Sentry.init({
-  dsn: 'YOUR_DSN',
-  environment: 'production',
-  tracesSampleRate: 0.2,
-});
-// #endif
-
-// #ifdef MP-WEIXIN || MP-ALIPAY || MP-BAIDU || MP-TOUTIAO || MP-QQ || MP-KUAISHOU || MP-DINGTALK
-Sentry = require('sentry-miniapp');
-Sentry.init({
-  dsn: 'YOUR_DSN',
-  environment: 'production',
-  tracesSampleRate: 0.2,
-});
-// #endif
-
-export default Sentry;
-```
-
-Both sides report to the same Sentry DSN so all errors land in a single project. For Taro, use `process.env.TARO_ENV === 'h5'` to branch similarly.
-
-### 4. Are network requests included with error events?
-
-**Yes, and it's on by default.** The SDK enables `NetworkBreadcrumbs` out of the box, which patches `wx.request` / `my.httpRequest` and records each request as a `category: xhr` breadcrumb. Those breadcrumbs ride along with the **next captured error event** (same as `@sentry/browser`), so you'll see the request trail leading up to the error in the event's **Breadcrumbs** section.
-
-- **Fields by default:** `url` / `method` / `status_code` / `duration`; failed requests are `error` level, slow ones (>3s) are `warning`.
-- **Bodies are NOT included by default.** Enable `traceNetworkBody: true` to capture request/response bodies (with built-in sensitive-field scrubbing; use `denyBodyUrls` to exclude specific URLs):
-
-  ```js
-  Sentry.init({ dsn: '...', traceNetworkBody: true });
-  ```
-
-- **No extra config for uni-app / Taro:** `uni.request` / `Taro.request` ultimately call the patched global `wx.request`, so they're captured too.
-
-If an error has no network breadcrumb, it's usually one of:
-
-1. **No request happened before the error fired** (e.g. calling `captureException` right on page load). To verify, make a request first and trigger the error in its callback:
-
-   ```js
-   wx.request({
-     url: 'https://httpbin.org/get',
-     success() {
-       Sentry.captureException(new Error('net test'));
-     },
-   });
-   ```
-
-   You should then see a `category: xhr` breadcrumb on the event.
-
-2. **`Sentry.init` ran after the request.** The patch is installed during `init`, so requests fired before `init` aren't captured. Always call `Sentry.init` before `App()` / any business request.
-
-### 5. Errors in uni-app (Vue) components aren't reported / reporting rate is very low?
-
-With **uni-app** (Vue under the hood) you may hit "`sampleRate` is 1 but only an occasional error shows up". The reason: **Vue catches errors thrown inside components (render / lifecycle / watchers / methods invoked from `@click`) with its own error handler — by default it only logs to console and does NOT bubble them to `wx.onError`**, so the SDK never sees them. Only errors that escape Vue (e.g. `setTimeout` callbacks, unhandled promises, hard crashes) get through, which is why reporting looks sporadic.
-
-Wire Vue's `errorHandler` to Sentry so component errors are reported:
-
-**uni-app Vue3 (`main.js` / `main.ts`, the current default):**
-
-```js
-import Sentry from '@/utils/sentry'; // your sentry-miniapp init wrapper
-import { createSSRApp } from 'vue';
-import App from './App.vue';
-
-export function createApp() {
-  const app = createSSRApp(App);
-  app.config.errorHandler = (err, instance, info) => {
-    Sentry.captureException(err, { extra: { lifecycleHook: info } });
-    console.error(err);
-  };
-  return { app };
-}
-```
-
-**Vue2 (older uni-app):**
-
-```js
-Vue.config.errorHandler = (err, vm, info) => {
-  Sentry.captureException(err);
-  console.error(err);
-};
-```
-
-> **Taro is not Vue.** Taro defaults to **React** (and also supports Vue). With **Vue**, wire `errorHandler` the same way; with **React**, React does not silently swallow component errors like Vue (an uncaught render error propagates upward), but you can add an **Error Boundary** to forward render errors to Sentry with richer context:
->
-> ```jsx
-> class SentryBoundary extends React.Component {
->   componentDidCatch(error, info) {
->     Sentry.captureException(error, { extra: info });
->   }
->   render() {
->     return this.props.children;
->   }
-> }
-> // Wrap your root: <SentryBoundary><App /></SentryBoundary>
-> ```
-
-This also improves delivery: once `errorHandler` / the boundary catches the error the app keeps running, so the in-flight report request completes (a hard crash would otherwise kill it).
+> Full answers on the **[docs site · FAQ](https://sentry-miniapp.pages.dev/guide/faq)**.
 
 ---
 
-## Documentation
+## 📖 Documentation
 
 | Document | Description |
 |----------|-------------|
-| [SourceMap Configuration Guide](./docs/SOURCEMAP_GUIDE.md) | End-to-end SourceMap setup, build tools, CI/CD, verification & troubleshooting |
-| [Multi-Platform Compatibility Report](./docs/MultiPlatformCompatibilityReport.md) | Platform API compatibility matrix and differences |
-| [Example Project](./examples/wxapp/) | Complete WeChat mini program integration example |
-| [Development Guide](./DEVELOPMENT.md) | Local development setup and debugging |
-| [Contributing Guide](./CONTRIBUTING.md) | How to contribute to the project |
+| [Documentation site](https://sentry-miniapp.pages.dev/) | Getting started / capability matrix / FAQ / Source Map / examples (recommended, with search) |
+| [Taro guide](https://sentry-miniapp.pages.dev/guide/taro) · [uni-app guide](https://sentry-miniapp.pages.dev/guide/uniapp) | Cross-platform framework setup & component error handling |
+| [Source Map Configuration Guide](./docs/SOURCEMAP_GUIDE.md) | End-to-end setup, build tools, CI/CD, verification |
+| [Multi-Platform Compatibility Report](./docs/MultiPlatformCompatibilityReport.md) | Platform API differences |
+| [Examples](./examples/) | wxapp (native) / taro (React) / uniapp (Vue) runnable examples |
+| [Development Guide](./DEVELOPMENT.md) · [Contributing Guide](./CONTRIBUTING.md) | Local dev, debugging & contributing |
 
 ---
 
-## Community
-
-Have questions or want to discuss mini program monitoring? Join our community.
+## 💬 Community
 
-Due to WeChat group QR code expiration (7-day limit), please add the author on WeChat (**note: sentry-miniapp**) to be invited to the group:
+Have questions or want to discuss mini program monitoring? Due to WeChat group QR code expiration (7-day limit), please add the author on WeChat (**note: sentry-miniapp**) to be invited to the group:
 
 <img src="docs/qrcode/zhiyao.jpeg" alt="Author WeChat QR Code" width="200" style="border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1);" />