Sentry Miniapp SDK

Sentry Mini Program SDK Setup

Use this skill when a user wants to integrate or troubleshoot sentry-miniapp in a consumer application. Discover the application's runtime, installed SDK and entry point before choosing code. This guide covers the stable 2.x contract.

1. Inspect the consumer

Read project instructions and inspect the relevant application directory. Prefer rg; exclude generated bundles and dependencies when searching source.

rg --files -g 'package.json' -g '*lock*' -g '*project*.json' -g 'app.json' \
  -g '*app.{js,ts,tsx,vue}' -g '*main.{js,ts}' \
  -g '*config.{js,ts,mjs}' -g '!node_modules' -g '!dist'
rg -n 'sentry-miniapp|@tarojs/|@dcloudio/uni-' package.json
rg -n 'Sentry\.init|sentry-miniapp|errorHandler|componentDidCatch' \
  src app.js app.ts -g '!node_modules' -g '!dist'

Adjust search roots to files that exist; these commands illustrate discovery, not a required directory layout.

Determine:

• Installed version and package manager. Read the lockfile and installed package metadata; a manifest range alone may not identify the resolved version.
• Release targets. Read framework configuration and platform globals. WeChat's project.config.json, Alipay's mini.project.json, ByteDance's project.tt.json and Baidu's project.swan.json are useful clues. Confirm QQ, DingTalk and Kuaishou from actual target configuration.
• Framework and entry. Native apps commonly use app.js/app.ts; Taro uses src/app.tsx or its configured entry; Vue 3 uni-app usually initializes from src/main.js/main.ts.
• Existing monitoring and privacy policy. Preserve working error handlers, integrations, sampling and consent requirements.
• Sentry deployment and build pipeline. Version support and final JS/map matching affect which features can be verified.

2. Choose the SDK version and features

An unqualified install selects the current stable release; sentry-miniapp@2 selects the stable 2.x line. Use @next only when the user explicitly chooses a prerelease. Do not silently migrate an existing 1.x application. Use the version and migration guide, including its fixed 1.x documentation archive.

2.0 uses Core v11 and stream spans. Check the target Sentry deployment against the guide's support baseline; successful error ingestion alone does not prove support for spans, Logs, Metrics or Sessions.

Implement the requested coverage. Resolve routine setup choices from the project and user intent; ask only for missing information that affects the result.

Load only the references needed for the work. Automatic capture depends on available host APIs; optional Performance observers and FPS are not universal platform capabilities.

3. Install and initialize

Use the consumer's existing package manager. For a chosen 2.x release, pin the resolved version and retain the lockfile:

npm install --save-exact sentry-miniapp@2
# Or, in a Yarn project:
yarn add --exact sentry-miniapp@2

For native WeChat projects, run Tools → Build npm in the developer tools after installation or updates. Check the package.json/miniprogramRoot layout against the native installation guide; framework projects use their own build pipeline.

Copy the complete DSN from the target Sentry project; do not construct its hostname. Configure the exact envelope request host as a legal request domain, or configure the chosen tunnel's host. Verify with device debugging and domain-check bypass disabled.

Initialize once, as early as practical, before native App() registration and business requests. In framework projects, put initialization in a dedicated module imported before the application module. Do not put init() inside a temporary scope or an unfinished async span.

// Native app.js
const Sentry = require('sentry-miniapp');

Sentry.init({
  dsn: 'YOUR_DSN', // Copy the complete project DSN.
  release: 'my-miniapp@1.0.0',
  environment: 'production',
});

App({
  // Existing application configuration.
});

For Taro and uni-app, follow their actual entry and preserve existing framework error handling:

• Taro initialization and React Error Boundary
• uni-app initialization and Vue errorHandler

H5 needs the official browser/framework SDK through target-specific imports. sentry-miniapp does not provide browser DOM or fetch/XHR instrumentation.