sentry-miniapp brings Sentry to Chinese mini programs and mini games

The gap is that mini programs have no Sentry SDK

sentry-miniapp exists because the platform coverage of Sentry itself stops at the web. A mini program runs inside a host runtime with its own request model, its own permission rules and its own build pipeline, and the standard browser SDK has no way to reach it. This SDK is listed as a Sentry Community SDK, which is the category for third party implementations built against the Sentry protocol, and the package covers WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk and Kuaishou mini programs, as well as WeChat and Douyin mini games. It works with native projects and with the Taro and uni-app frameworks. The problem it is aimed at is stated plainly in the project description: connecting mini programs and mini games to Sentry, combining device, operation and request records to investigate production errors, and turning on performance sampling on demand to analyse how long requests and business operations take. The alternative for most teams was a home grown logging endpoint or nothing at all.

The requirement that trips people up is the server version

Before anything else, the documentation names a hard boundary. The 2.x line is written against the Sentry cloud service or a self-hosted Sentry at 26.4.2 or newer, and older self-hosted backends are not in the 2.x support range. The project adds a sentence that deserves to be read twice: receiving error events does not prove that the other monitoring capabilities are compatible. That is a distinction many teams would otherwise learn the hard way, because a setup can look correct when error reporting works and then quietly fail on performance data, traces or context enrichment. The version selection and migration guide exists for the same reason, covering both 1.x projects that need to upgrade and self-hosted setups that cannot yet move. The release history shows how fast this line is moving, with v2.1.0 and v2.2.0 both on 2026-10-15 and v2.2.1 on 2026-10-19, so the migration path matters more here than in a typical SDK.

Installing it and initialising at the top of the entry file

The package installs from npm.

npm install sentry-miniapp

Native WeChat projects also need the build npm step run in the developer tools, while Taro and uni-app projects let the framework handle dependencies. If npm is not an option, a UMD build called sentry-miniapp.umd.js is published on GitHub Releases to drop into the project's lib/ directory, with the import changed to require that file instead. The initialisation order is the part that matters, since the documentation says to initialise at the very top of the entry file, app.js or app.ts, before App() is called.

const Sentry = require('sentry-miniapp');

The init call then takes the DSN copied from the Sentry project, a release string, and an environment, and the release value has to match the one used when source maps are uploaded, which is the single most common cause of a stack trace that will not resolve to source. The equivalent call in prose form is Sentry.init({ dsn: 'YOUR_DSN', release: '[email protected]', environment: 'production' }), followed by the existing App({ onLaunch() {} }) call. Once that is in place you verify the connection with one line.

Sentry.captureException(new Error('sentry test'));

If no event shows up, the documented checklist is the DSN, the legal domain list, the initialisation position and the sampling configuration, and the project points at the mini program backend for adding the Sentry reporting domain to the request allow list.

Performance sampling and tracing are opt-in, and cost traffic

The minimum integration does not start performance sampling, and the documentation is explicit about that. Once error reporting is confirmed working, you configure tracesSampleRate according to your project's traffic, and only then does the SDK record request and business step durations, with tracing configured to correlate with backend operations that already report to Sentry. The design intent is visible in the problem table. A user reports an error that is hard to reproduce locally becomes an issue in Sentry that can be reconstructed with device, page, operation and request context. A login or payment flow that became slow becomes a question of which step was slow. A business failure that threw no exception becomes a queryable record, because the SDK lets you log business events and metrics deliberately, count failures and look at duration distributions. The trade-off is the usual one for sampling, and it is worth naming here: a sample rate is a guess about which failures you will see, and a rate tuned too high will not only cost traffic but drown the signal you are trying to read.

Source maps, page replay and the cases the SDK handles for you

Two features go beyond error reporting. The first is source map handling, which turns a stack trace of a bundled file and a line number into a location in your original source with the surrounding code, and the project documents a dedicated page for uploading source maps and for troubleshooting Debug IDs and the merged files WeChat produces. The second is experimental WeChat page replay, which records the sampled layout, text changes and clicks of selected pages so you can see the interface change before the error. It needs sentry-miniapp 2.1.0 or newer, requires the replay integration to be installed and page markers generated, and currently applies only to ordinary WebView mini programs on WeChat. From 2.2.0, Taro 4 with webpack5 and uni-app with Vue 3 and Vite generate those markers automatically after one build plugin is configured, so a normal build or dev run produces them without editing templates page by page. The source examples also support local recording and playback, exporting a recording to view in a desktop browser without using Sentry cloud quota. The README also lists the cases the SDK covers by default, and the boundary is explicit: automatic capture depends on platform capability, React and Vue component errors need the framework error handler wired in, and mini game frame rate monitoring has to be turned on actively.

Reliability and privacy are configuration, not defaults

Two design decisions are worth understanding before you point this at production traffic. The first is the local queue. When a user is on a weak network and the monitoring request itself fails, data that matches the policy is held in a bounded local queue and retried when the network recovers. The second is the consent gate. If regulations require the user to accept a privacy policy before monitoring data may leave the device, the SDK can be configured to pause Sentry network sends until consent is given and then attempt to send the buffered data. Both of these are listed in the project's table of problems solved, and both are off unless you turn them on and configure them to your policy. That is a fair design for a Chinese market where privacy rules differ by platform, but it means the defaults are not a complete answer, and the settings pages for reliable delivery and privacy consent are part of the integration, not an optional extra. The project also asks contributors to strip auth tokens, app secrets and user private data before sharing configuration and logs.

Where sentry-miniapp is the wrong choice

Three limits. The first is platform coverage inside the platforms. Automatic capture depends on what each host runtime exposes, so two mini programs on the same framework can end up with different instrumentation, and the support range page is the place to check rather than assume. The second is that the SDK is not a replacement for framework level error handling. A React or Vue render error still needs the framework handler connected, and a mini game frame rate problem still needs frame monitoring switched on, so the promise of automatic collection has a caveat that is easy to skip. The third is the version coupling on the server, which was covered above but is worth restating as a decision criterion: an organisation on an older self-hosted Sentry cannot use the current line, and the migration guide is the place to find out what that means for them. A smaller point is the licence and project shape. The code is MIT licensed, and the repository carries the usual governance files, an ARCHITECTURE.md, a DEVELOPMENT.md, a vite config, a vitest config, husky, commitlint and separate example projects for wxapp, Taro and uni-app, which tells you it is maintained as a real package rather than a script, but it is still one maintainer's package, so a plan for the case where it stops is worth having.

Editorial conclusion

Adopt sentry-miniapp if you run mini programs or mini games and want the same Sentry backend, source map workflow and issue triage your web and backend services already use. Skip it if your Sentry is self-hosted below 26.4.2, because the 2.x line does not support it, and skip it if you need automatic capture of React or Vue component errors without wiring the framework handler yourself. Before your first release, pin the release string to the same value you upload source maps under, because a mismatch is what makes a stack trace resolve to a bundled file instead of your source.

Frequently asked questions

Official sources

1. License: MIT
2. lizhiyao/sentry-miniapp on GitHub
3. Project website
4. README
5. Releases