sentry-miniapp 1.11.1 → 1.11.3

package/README.en.md

@@ -7,26 +7,31 @@
 ![test coverage](https://img.shields.io/badge/test%20coverage-100%25-brightgreen.svg)
 [![Sentry Community SDK](https://img.shields.io/badge/Sentry-Community%20SDK-362d59?logo=sentry)](https://docs.sentry.io/platforms/#sdks-supported-by-our-community)
 [![license](https://img.shields.io/github/license/lizhiyao/sentry-miniapp)](./LICENSE)
+[![docs](https://img.shields.io/badge/docs-sentry--miniapp.pages.dev-3eaf7c?logo=readthedocs&logoColor=white)](https://sentry-miniapp.pages.dev/)
 
 [简体中文](./README.md) | English
 
 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.
 
@@ -34,394 +39,161 @@ 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.
-
----
-
-## Advanced Usage
-
-After initialization, the SDK works automatically in the background. You can also use the following APIs for manual instrumentation.
+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).
 
-### 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)
+> ⚠️ `addBreadcrumb` is not reported on its own — it only ships with the next event. Calling it without capturing an event leaves your dashboard empty.
 
-```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');
-
-// 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
-
-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.
+## 🗺️ Source Map
 
-**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)**.
-
----
-
-## 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...'
-});
-```
+> 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)**.
 
 ---
 
-## Bundle Size Optimization (Zero Main Package Overhead)
+## 🎮 Mini Game Support
 
-Mini program "main package" size is limited (typically 2MB). `sentry-miniapp` includes the full `@sentry/core` engine and multi-platform adapters, totaling ~100KB.
+`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.
 
-If main package size is a concern, use **subpackage async loading** or **dynamic loading** to move the SDK entirely into a subpackage.
+> Capability matrix and performance-reporting details: [docs site · Platforms & Capabilities](https://sentry-miniapp.pages.dev/guide/platforms).
 
-### Option A: WeChat / Alipay (Recommended)
-
-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);
-    });
-  }
-});
-```
+## 📦 Bundle Size Optimization
 
-*This way, Sentry's ~100KB is counted against `subpackageA`'s size — zero main package overhead!*
+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.
 
-### 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
-
-### 1. Do I need to manually report errors in `onError`?
-
-**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**:
+## ❓ FAQ (quick reference)
 
-```ts
-// utils/sentry.ts
-let Sentry: any;
+- **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.
 
-// #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.
+> 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);" />