@lark.js/sentry 0.0.5 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,782 @@
1
+ # @lark.js/sentry
2
+
3
+ `@lark.js/sentry` is a browser monitoring and analytics SDK for page views, declarative clicks, runtime errors, resource errors, HTTP requests, performance metrics, exposure tracking, white-screen detection, offline reporting, and screen record context.
4
+
5
+ The core entry is framework agnostic. React and Vue integrations are published as dedicated subpath exports so non-framework users do not load framework dependencies.
6
+
7
+ ## Installation
8
+
9
+ ```bash
10
+ npm install @lark.js/sentry
11
+ ```
12
+
13
+ React and Vue are optional peer dependencies. Install them only when the matching integration is used.
14
+
15
+ ```bash
16
+ npm install react
17
+ ```
18
+
19
+ ```bash
20
+ npm install vue
21
+ ```
22
+
23
+ ## Package Exports
24
+
25
+ ```ts
26
+ import { init, destroy, isInitialized, pluginEnable } from "@lark.js/sentry";
27
+ import {
28
+ PerformancePlugin,
29
+ ScreenRecordPlugin,
30
+ ExposurePlugin,
31
+ } from "@lark.js/sentry/plugins";
32
+ import { ReactErrorBoundary } from "@lark.js/sentry/react";
33
+ import { vuePlugin } from "@lark.js/sentry/vue";
34
+ ```
35
+
36
+ Each public export provides ESM, CJS, and TypeScript declaration files.
37
+
38
+ ## Quick Start
39
+
40
+ ```ts
41
+ import { init, pluginEnable } from "@lark.js/sentry";
42
+ import {
43
+ PerformancePlugin,
44
+ ScreenRecordPlugin,
45
+ ExposurePlugin,
46
+ } from "@lark.js/sentry/plugins";
47
+
48
+ init({
49
+ dsn: "/api/log",
50
+ projectId: "frontend-app",
51
+ userId: "anonymous",
52
+ });
53
+
54
+ pluginEnable(PerformancePlugin);
55
+ pluginEnable(ScreenRecordPlugin);
56
+ pluginEnable(ExposurePlugin);
57
+ ```
58
+
59
+ `dsn` must be a non-empty string. If `dsn` is empty, initialization is rejected.
60
+
61
+ ## Lifecycle APIs
62
+
63
+ ### init
64
+
65
+ `init(options)` validates the input with zod, merges it with default options, writes runtime configuration, installs capture listeners, starts page-view lifecycle tracking, and initializes visitor identity when enabled.
66
+
67
+ ```ts
68
+ import { init } from "@lark.js/sentry";
69
+
70
+ init({
71
+ dsn: "/api/log",
72
+ projectId: "checkout-web",
73
+ userId: "user-001",
74
+ enableFetch: true,
75
+ enableXhr: true,
76
+ enableClick: true,
77
+ });
78
+ ```
79
+
80
+ ### destroy
81
+
82
+ `destroy()` cleans plugin instances, event subscriptions, browser listeners, and decorated global methods.
83
+
84
+ ```ts
85
+ import { destroy } from "@lark.js/sentry";
86
+
87
+ destroy();
88
+ ```
89
+
90
+ Use it when resetting tests, unloading a micro-frontend, or dynamically disabling monitoring.
91
+
92
+ ### isInitialized
93
+
94
+ ```ts
95
+ import { init, isInitialized } from "@lark.js/sentry";
96
+
97
+ if (!isInitialized()) {
98
+ init({ dsn: "/api/log" });
99
+ }
100
+ ```
101
+
102
+ ## Configuration
103
+
104
+ `init` accepts partial options. Values not provided by the caller use SDK defaults.
105
+
106
+ | Option | Type | Default | Description |
107
+ | ---------------------------- | ---------------------- | --------------------------------------------------- | ------------------------------------------------------ |
108
+ | `dsn` | `string` | `""` | Report endpoint. Required for initialization. |
109
+ | `projectId` | `string` | `"unknown"` | Frontend project identifier. |
110
+ | `userId` | `string` | `"unknown"` | Current user identifier. |
111
+ | `disabled` | `boolean` | `false` | Disable the SDK. |
112
+ | `enableXhr` | `boolean` | `true` | Capture XMLHttpRequest requests. |
113
+ | `enableFetch` | `boolean` | `true` | Capture fetch requests. |
114
+ | `enableClick` | `boolean` | `true` | Capture declarative click events. |
115
+ | `enableError` | `boolean` | `true` | Capture runtime and resource errors. |
116
+ | `enableUnhandledRejection` | `boolean` | `true` | Capture unhandled promise rejections. |
117
+ | `enableHashChange` | `boolean` | `true` | Capture hash navigation. |
118
+ | `enableHistory` | `boolean` | `true` | Capture history navigation. |
119
+ | `enablePerformance` | `boolean` | `true` | Enable performance-related capture. |
120
+ | `enableScreenRecord` | `boolean` | `true` | Enable screen-record-related reporting. |
121
+ | `enableWhiteScreen` | `boolean` | `true` | Enable white-screen detection. |
122
+ | `enableFingerprint` | `boolean` | `false` | Enable FingerprintJS anonymous visitor identity. |
123
+ | `anonymousId` | `string` | `"unknown"` | SDK-generated anonymous visitor id. |
124
+ | `visitorId` | `string` | `"unknown"` | Backend-bound visitor id. |
125
+ | `useImageReport` | `boolean` | `false` | Allow image transport. |
126
+ | `screenRecordDurationMs` | `number` | `3000` | Rolling screen record window length. |
127
+ | `screenRecordEventTypes` | `EventType[]` | `[Error, Xhr, Fetch, Resource, UnhandledRejection]` | Event types that trigger screen record reporting. |
128
+ | `hasSkeleton` | `boolean` | `false` | Whether the page has a skeleton screen. |
129
+ | `rootCssSelectors` | `string[]` | `["html", "body", "#app", "#root"]` | Root selectors used by white-screen detection. |
130
+ | `clickThrottleDelay` | `number` | `0` | Click capture throttle delay in milliseconds. |
131
+ | `requestTimeoutMilliseconds` | `number` | `3000` | Request timeout in milliseconds. |
132
+ | `maxBreadcrumbs` | `number` | `30` | Breadcrumb capacity. |
133
+ | `repeatCodeError` | `boolean` | `false` | Report duplicate code errors. |
134
+ | `enableHttpPerformance` | `boolean` | `false` | Report successful HTTP requests as performance events. |
135
+ | `ignoreErrors` | `(string \| RegExp)[]` | `[]` | Runtime error ignore rules. |
136
+ | `excludeApis` | `(string \| RegExp)[]` | `[]` | HTTP request ignore rules. |
137
+ | `cacheMaxLength` | `number` | `10` | Maximum batch size. |
138
+ | `cacheWaitingTime` | `number` | `2000` | Batch wait time in milliseconds. |
139
+ | `maxQueueLength` | `number` | `200` | Maximum queued events while offline or retrying. |
140
+ | `retryIntervalMilliseconds` | `number` | `60000` | Server recovery probe interval. |
141
+ | `offlineCacheKey` | `string` | `"lark_sentry_offline_cache"` | localStorage key for offline cache. |
142
+ | `tracesSampleRate` | `number` | `1` | Sampling rate from 0 to 1. |
143
+ | `onBeforePushBreadcrumb` | `function` | `undefined` | Hook before storing a breadcrumb. |
144
+ | `onBeforeReportData` | `function` | `undefined` | Hook before one event enters Reporter queue. |
145
+ | `beforePushEventList` | `function` | `undefined` | Hook before a batch enters transport. |
146
+ | `afterSendData` | `function` | `undefined` | Hook after a batch enters transport successfully. |
147
+ | `handleHttpError` | `function` | `undefined` | Custom HTTP error callback. |
148
+
149
+ Example production configuration:
150
+
151
+ ```ts
152
+ import { init } from "@lark.js/sentry";
153
+
154
+ init({
155
+ dsn: "https://example.com/api/log",
156
+ projectId: "production-web",
157
+ userId: "unknown",
158
+ enableFingerprint: true,
159
+ enableHttpPerformance: true,
160
+ tracesSampleRate: 1,
161
+ excludeApis: ["https://example.com/api/log"],
162
+ ignoreErrors: [/ResizeObserver loop limit exceeded/],
163
+ });
164
+ ```
165
+
166
+ ## Report Data
167
+
168
+ Reporter sends `IReportData` objects to the configured `dsn`.
169
+
170
+ | Field | Description |
171
+ | ------------ | ------------------------------------------ |
172
+ | `id` | Reporter instance id. |
173
+ | `type` | Event type. |
174
+ | `name` | Event name. |
175
+ | `message` | Event message. |
176
+ | `status` | `OK` or `Error`. |
177
+ | `time` | Formatted time. |
178
+ | `timestamp` | Numeric timestamp. |
179
+ | `url` | Current page URL. |
180
+ | `userId` | User identifier. |
181
+ | `projectId` | Project identifier. |
182
+ | `sdkVersion` | SDK version. |
183
+ | `deviceInfo` | Device, browser, OS, and fingerprint data. |
184
+ | `payload` | Original event payload. |
185
+
186
+ ## Event Types
187
+
188
+ The SDK can report the following event categories:
189
+
190
+ | Type | Description |
191
+ | -------------------------- | ------------------------------- |
192
+ | `XMLHttpRequest` | XHR request. |
193
+ | `fetch` | fetch request. |
194
+ | `Click` | Declarative click. |
195
+ | `Event hashchange` | Hash navigation. |
196
+ | `History` | History navigation. |
197
+ | `Resource` | Static resource load failure. |
198
+ | `Event unhandledrejection` | Unhandled promise rejection. |
199
+ | `Error` | JavaScript runtime error. |
200
+ | `Vue` | Vue error. |
201
+ | `React` | React error. |
202
+ | `Performance` | Performance metric. |
203
+ | `ScreenRecord` | Screen record payload. |
204
+ | `Exposure` | Exposure duration event. |
205
+ | `WhiteScreen` | White-screen event. |
206
+ | `Custom` | Custom business event. |
207
+ | `PV` | Page view and dwell-time event. |
208
+
209
+ ## Error Capture
210
+
211
+ The SDK captures:
212
+
213
+ - `window` `error` events.
214
+ - Static resource load errors.
215
+ - `console.error` error objects or error text.
216
+ - Unhandled promise rejections.
217
+ - React ErrorBoundary errors.
218
+ - Vue `app.config.errorHandler` errors.
219
+
220
+ Duplicate code errors are deduplicated by default. Enable duplicate reporting with:
221
+
222
+ ```ts
223
+ init({
224
+ dsn: "/api/log",
225
+ repeatCodeError: true,
226
+ });
227
+ ```
228
+
229
+ Ignore known noise:
230
+
231
+ ```ts
232
+ init({
233
+ dsn: "/api/log",
234
+ ignoreErrors: ["Script error.", /ResizeObserver loop limit exceeded/],
235
+ });
236
+ ```
237
+
238
+ ## HTTP Capture
239
+
240
+ The SDK decorates `XMLHttpRequest.prototype.open`, `XMLHttpRequest.prototype.send`, and `globalThis.fetch`. It captures method, URL, status code, elapsed time, request data, response data, and `Server-Timing`.
241
+
242
+ Status classification:
243
+
244
+ | Status code | SDK status |
245
+ | ------------ | ---------- |
246
+ | 100 to 399 | `OK` |
247
+ | 400 to 599 | `Error` |
248
+ | Other values | `Error` |
249
+
250
+ Exclude report endpoints or health checks:
251
+
252
+ ```ts
253
+ init({
254
+ dsn: "/api/log",
255
+ excludeApis: ["/api/log", /\/health$/],
256
+ });
257
+ ```
258
+
259
+ Report successful HTTP requests as performance events:
260
+
261
+ ```ts
262
+ init({
263
+ dsn: "/api/log",
264
+ enableHttpPerformance: true,
265
+ });
266
+ ```
267
+
268
+ ## Page Views and Dwell Time
269
+
270
+ The SDK reports an initial `PageLoad` PV event during initialization.
271
+
272
+ On hash or history route changes, it:
273
+
274
+ - Deduplicates unchanged URLs.
275
+ - Reports `PageDwell` for the previous page.
276
+ - Reports a new PV for the next page.
277
+ - Flushes current dwell time on `beforeunload` when possible.
278
+
279
+ Dwell time less than or equal to 100 ms is ignored to reduce noise.
280
+
281
+ Manual page-view reporting:
282
+
283
+ ```ts
284
+ import { tracePageView } from "@lark.js/sentry";
285
+
286
+ tracePageView({
287
+ name: "ProductDetail",
288
+ message: location.href,
289
+ extra: {
290
+ productId: "sku-001",
291
+ },
292
+ });
293
+ ```
294
+
295
+ ## Declarative Clicks
296
+
297
+ Declarative click tracking uses `s-lark-*` attributes. Plain clicks are not reported unless the clicked element or one of its composed path ancestors has a tracking attribute.
298
+
299
+ ```html
300
+ <section s-lark-view="profile-card" s-lark-src="home">
301
+ <button s-lark-ev="save-profile" s-lark-msg="Save">Save</button>
302
+ </section>
303
+ ```
304
+
305
+ Reserved attributes:
306
+
307
+ | Attribute | Description |
308
+ | ------------- | ------------------------------ |
309
+ | `s-lark-ev` | Explicit event ID. |
310
+ | `s-lark-msg` | Human-readable message. |
311
+ | `s-lark-view` | View ID and event ID fallback. |
312
+
313
+ Custom `s-lark-*` attributes become `params`.
314
+
315
+ ```html
316
+ <a
317
+ s-lark-ev="open-banner"
318
+ s-lark-msg="Open campaign banner"
319
+ s-lark-campaign="spring"
320
+ s-lark-rank="1"
321
+ >
322
+ Campaign
323
+ </a>
324
+ ```
325
+
326
+ The reported click payload (`DeclarativeClickData`) includes:
327
+
328
+ | Field | Type | Description |
329
+ | ---------------- | ------------------------------------------ | ----------------------------------------------------------------------- |
330
+ | `ev` | `string` | Event ID (from `s-lark-ev`, `title`, `s-lark-view`, or tag). |
331
+ | `msg` | `string` | Human-readable message (from `s-lark-msg`, text, `aria-label`, or tag). |
332
+ | `triggerPageUrl` | `string` | Current page URL (`location.href`). |
333
+ | `x` | `number` | Click X coordinate (element offset + scroll offset). |
334
+ | `y` | `number` | Click Y coordinate (element offset + scroll offset). |
335
+ | `params` | `Readonly<Record<string, string \| null>>` | Custom `s-lark-*` attributes (excluding reserved keys). |
336
+ | `elementPath` | `string` | XPath-like path from element to body (max 128 characters). |
337
+ | `triggerTime` | `number` | `Date.now()` at click time. |
338
+
339
+ ## White-Screen Detection
340
+
341
+ White-screen detection samples viewport points after the page is ready and checks whether those points still resolve to configured root elements.
342
+
343
+ Default root selectors:
344
+
345
+ ```ts
346
+ ["html", "body", "#app", "#root"];
347
+ ```
348
+
349
+ ```ts
350
+ init({
351
+ dsn: "/api/log",
352
+ enableWhiteScreen: true,
353
+ rootCssSelectors: ["html", "body", "#app"],
354
+ });
355
+ ```
356
+
357
+ Skeleton-screen pages can enable skeleton mode:
358
+
359
+ ```ts
360
+ init({
361
+ dsn: "/api/log",
362
+ enableWhiteScreen: true,
363
+ hasSkeleton: true,
364
+ });
365
+ ```
366
+
367
+ ## Visitor Identity
368
+
369
+ The SDK tracks three identity values:
370
+
371
+ | Field | Description |
372
+ | ------------- | ------------------------------------------------------------------- |
373
+ | `anonymousId` | Anonymous visitor id generated by FingerprintJS and stored locally. |
374
+ | `visitorId` | Backend-bound visitor id. |
375
+ | `userId` | Current logged-in user id. |
376
+
377
+ Enable FingerprintJS:
378
+
379
+ ```ts
380
+ import { getIdentity, init } from "@lark.js/sentry";
381
+
382
+ init({
383
+ dsn: "/api/log",
384
+ enableFingerprint: true,
385
+ });
386
+
387
+ console.log(getIdentity());
388
+ ```
389
+
390
+ Update user and visitor ids:
391
+
392
+ ```ts
393
+ import { setUserId, setVisitorId } from "@lark.js/sentry";
394
+
395
+ setUserId("user-001");
396
+ setVisitorId("visitor-001");
397
+ ```
398
+
399
+ Read identity:
400
+
401
+ ```ts
402
+ import { getIdentity } from "@lark.js/sentry";
403
+
404
+ const identity = getIdentity();
405
+ ```
406
+
407
+ `anonymousId` is stored in localStorage with the key `lark_sentry_anonymous_id`.
408
+
409
+ ## Reporter
410
+
411
+ Reporter is the unified data outlet. It transforms captured payloads into report data and sends batches to `dsn`.
412
+
413
+ Reporter behavior:
414
+
415
+ - Batches events.
416
+ - Applies sampling through `tracesSampleRate`.
417
+ - Persists offline events to localStorage.
418
+ - Flushes cached events after network recovery.
419
+ - Probes server recovery with HEAD requests after failed fetch reports.
420
+ - Avoids concurrent flush races with an `isFlushing` guard.
421
+ - Supports `sendBeacon`, image, and fetch transports.
422
+
423
+ Transport priority:
424
+
425
+ 1. Use `navigator.sendBeacon` for batches up to 60 KB.
426
+ 2. Use image transport when `useImageReport` is true and the batch is up to 2 KB.
427
+ 3. Use fetch POST as the fallback.
428
+
429
+ Flush offline cache manually:
430
+
431
+ ```ts
432
+ import { sendLocal } from "@lark.js/sentry";
433
+
434
+ await sendLocal();
435
+ ```
436
+
437
+ ## Reporter Hooks
438
+
439
+ Register hooks after initialization or provide equivalent hooks in `init` options.
440
+
441
+ ```ts
442
+ import {
443
+ afterSendData,
444
+ beforePushEventList,
445
+ beforeSendData,
446
+ } from "@lark.js/sentry";
447
+
448
+ beforeSendData((data) => {
449
+ if (data.type === "Click") {
450
+ return false;
451
+ }
452
+ return data;
453
+ });
454
+
455
+ beforePushEventList((eventList) => {
456
+ return eventList.filter((item) => item.status !== "OK");
457
+ });
458
+
459
+ afterSendData((eventList) => {
460
+ console.log("reported", eventList.length);
461
+ });
462
+ ```
463
+
464
+ Equivalent initialization form:
465
+
466
+ ```ts
467
+ init({
468
+ dsn: "/api/log",
469
+ onBeforeReportData(data) {
470
+ return data;
471
+ },
472
+ beforePushEventList(eventList) {
473
+ return eventList;
474
+ },
475
+ afterSendData(eventList) {
476
+ console.log(eventList.length);
477
+ },
478
+ });
479
+ ```
480
+
481
+ ## Manual APIs
482
+
483
+ ### traceError
484
+
485
+ ```ts
486
+ import { traceError } from "@lark.js/sentry";
487
+
488
+ try {
489
+ throw new Error("Unexpected state");
490
+ } catch (error) {
491
+ traceError(error);
492
+ }
493
+ ```
494
+
495
+ ### tracePerformance
496
+
497
+ ```ts
498
+ import { tracePerformance } from "@lark.js/sentry";
499
+
500
+ tracePerformance({
501
+ name: "SearchLatency",
502
+ message: "/api/search",
503
+ value: 128,
504
+ });
505
+ ```
506
+
507
+ ### traceCustomEvent
508
+
509
+ ```ts
510
+ import { traceCustomEvent } from "@lark.js/sentry";
511
+
512
+ traceCustomEvent({
513
+ name: "CheckoutSuccess",
514
+ message: "Submit order",
515
+ extra: {
516
+ orderId: "order-001",
517
+ },
518
+ });
519
+ ```
520
+
521
+ ### tracePageView
522
+
523
+ ```ts
524
+ import { tracePageView } from "@lark.js/sentry";
525
+
526
+ tracePageView({
527
+ name: "ManualPageView",
528
+ message: location.href,
529
+ });
530
+ ```
531
+
532
+ ### getBaseInfo and getUserId
533
+
534
+ ```ts
535
+ import { getBaseInfo, getUserId } from "@lark.js/sentry";
536
+
537
+ const baseInfo = getBaseInfo();
538
+ const userId = getUserId();
539
+ ```
540
+
541
+ ### getIPs
542
+
543
+ `getIPs` attempts to collect WebRTC ICE candidate IP values in browsers that support the required APIs. It returns an empty array when unsupported.
544
+
545
+ ```ts
546
+ import { getIPs } from "@lark.js/sentry";
547
+
548
+ const ips = await getIPs();
549
+ ```
550
+
551
+ ## Plugin System
552
+
553
+ Plugins extend the SDK without coupling optional capabilities to the core entry. A plugin class extends `SentryPlugin`, implements `init`, and can implement `destroy` for cleanup.
554
+
555
+ ```ts
556
+ import { pluginEnable } from "@lark.js/sentry";
557
+ import { PerformancePlugin } from "@lark.js/sentry/plugins";
558
+
559
+ const plugin = pluginEnable(PerformancePlugin);
560
+ ```
561
+
562
+ Enabled plugins are stored in the plugin registry. `destroy()` calls each plugin's `destroy()` method when available.
563
+
564
+ ## PerformancePlugin
565
+
566
+ ```ts
567
+ import { pluginEnable } from "@lark.js/sentry";
568
+ import { PerformancePlugin } from "@lark.js/sentry/plugins";
569
+
570
+ pluginEnable(PerformancePlugin);
571
+ ```
572
+
573
+ The plugin collects:
574
+
575
+ - Web Vitals.
576
+ - Navigation Timing page-load metrics.
577
+ - Resource Timing metrics.
578
+ - Long Task entries.
579
+ - Fallback resource-element timing for dynamically inserted resources.
580
+ - `performance.measureUserAgentSpecificMemory` when supported.
581
+
582
+ Unsupported browser capabilities are skipped safely.
583
+
584
+ ## ScreenRecordPlugin
585
+
586
+ ```ts
587
+ import { pluginEnable } from "@lark.js/sentry";
588
+ import { ScreenRecordPlugin, unzipScreenRecord } from "@lark.js/sentry/plugins";
589
+
590
+ pluginEnable(ScreenRecordPlugin);
591
+
592
+ pluginEnable(ScreenRecordPlugin, {
593
+ durationMs: 5000,
594
+ });
595
+ ```
596
+
597
+ Screen recording is based on rrweb. The plugin keeps a rolling record window. When selected error or network events occur, the recent record window is reported as a `ScreenRecord` event.
598
+
599
+ Decode a record payload:
600
+
601
+ ```ts
602
+ const events = unzipScreenRecord(recordPayload);
603
+ ```
604
+
605
+ ## ExposurePlugin
606
+
607
+ ```ts
608
+ import { pluginEnable } from "@lark.js/sentry";
609
+ import { ExposurePlugin } from "@lark.js/sentry/plugins";
610
+
611
+ const exposure = pluginEnable(ExposurePlugin);
612
+ ```
613
+
614
+ Observe one element:
615
+
616
+ ```ts
617
+ const element = document.querySelector("#banner");
618
+
619
+ if (element) {
620
+ exposure.observe({
621
+ target: element,
622
+ threshold: 0.5,
623
+ params: {
624
+ bannerId: "spring-001",
625
+ },
626
+ });
627
+ }
628
+ ```
629
+
630
+ Observe multiple elements:
631
+
632
+ ```ts
633
+ const first = document.querySelector("#first");
634
+ const second = document.querySelector("#second");
635
+
636
+ if (first && second) {
637
+ exposure.observe([
638
+ {
639
+ target: first,
640
+ threshold: 0.5,
641
+ params: { position: "first" },
642
+ },
643
+ {
644
+ target: second,
645
+ threshold: 0.75,
646
+ params: { position: "second" },
647
+ },
648
+ ]);
649
+ }
650
+ ```
651
+
652
+ Cancel observation:
653
+
654
+ ```ts
655
+ exposure.unobserve(element);
656
+ exposure.unobserve([first, second]);
657
+ ```
658
+
659
+ Exposure events are reported when an observed element leaves the viewport after becoming visible. The payload contains threshold, observe time, show time, show end time, duration, and user params.
660
+
661
+ ## React Integration
662
+
663
+ ```tsx
664
+ import { init } from "@lark.js/sentry";
665
+ import { ReactErrorBoundary } from "@lark.js/sentry/react";
666
+
667
+ init({ dsn: "/api/log" });
668
+
669
+ export function App() {
670
+ return (
671
+ <ReactErrorBoundary fallback={<div>Something went wrong</div>}>
672
+ <Page />
673
+ </ReactErrorBoundary>
674
+ );
675
+ }
676
+ ```
677
+
678
+ `fallback` can also be a function:
679
+
680
+ ```tsx
681
+ <ReactErrorBoundary
682
+ fallback={(error, errorInfo) => (
683
+ <div>
684
+ {error.message}
685
+ {errorInfo.componentStack}
686
+ </div>
687
+ )}
688
+ >
689
+ <Page />
690
+ </ReactErrorBoundary>
691
+ ```
692
+
693
+ The boundary reports `React` events with the error, stack, and React `ErrorInfo`.
694
+
695
+ ## Vue 3 Integration
696
+
697
+ ```ts
698
+ import { createApp } from "vue";
699
+ import { vuePlugin } from "@lark.js/sentry/vue";
700
+ import App from "./app.vue";
701
+
702
+ const app = createApp(App);
703
+
704
+ app.use(vuePlugin, {
705
+ dsn: "/api/log",
706
+ projectId: "vue-app",
707
+ });
708
+
709
+ app.mount("#app");
710
+ ```
711
+
712
+ The plugin installs `app.config.errorHandler`, reports `Vue` events, and then calls the previous error handler if one existed.
713
+
714
+ ## Vite Dev-Server Plugin
715
+
716
+ The SDK provides a Vite plugin that creates a mock report endpoint during development, writing reported data to log files instead of sending it to a real server.
717
+
718
+ ```ts
719
+ // vite.config.ts
720
+ import { defineConfig } from "vite";
721
+ import { sentryPlugin } from "@lark.js/sentry/vite";
722
+
723
+ export default defineConfig({
724
+ // `url` should equals to @lark.js/sentry `init({ dsn: "/api/log" })` config `dsn`
725
+ plugins: [sentryPlugin({ url: "/api/log" })],
726
+ });
727
+ ```
728
+
729
+ ### Available Exports
730
+
731
+ | Export | Vite Version | Description |
732
+ | --------------- | ------------ | --------------------------------------- |
733
+ | `sentryPlugin` | Vite 6/8 | Default export. For current Vite. |
734
+ | `sentryPlugin7` | Vite 7 | For projects using Vite 7 specifically. |
735
+
736
+ ### Options
737
+
738
+ | Option | Type | Default | Description |
739
+ | ------ | -------- | ----------- | ---------------------------------------- |
740
+ | `url` | `string` | `"/sentry"` | The URL path to intercept POST requests. |
741
+
742
+ The plugin creates a `logs/` directory in `process.cwd()`, writes a timestamped log file (`sentry_YYYYMMDDHHMMSS.log`), parses each request body as JSON, and returns `{ code: 0, message: "success" }`.
743
+
744
+ ## Browser Compatibility
745
+
746
+ - `sendBeacon` is preferred for small batches.
747
+ - Image and fetch transports are used as fallbacks.
748
+ - `PerformanceObserver` powers Web Vitals, long task, and resource timing when available.
749
+ - `MutationObserver` is used as a fallback for dynamically inserted resources.
750
+ - `IntersectionObserver` is required by `ExposurePlugin`.
751
+ - `performance.measureUserAgentSpecificMemory` is optional.
752
+ - `@rrweb/record` is used only by the screen record plugin.
753
+
754
+ ## Quality Gates
755
+
756
+ ```bash
757
+ pnpm exec eslint ./sentry --quiet --ext .js,.jsx,.ts,.tsx
758
+ pnpm --filter @lark.js/sentry typecheck
759
+ pnpm --filter @lark.js/sentry test
760
+ pnpm test:coverage
761
+ pnpm build
762
+ ```
763
+
764
+ Coverage thresholds are 70 for lines, functions, branches, and statements.
765
+
766
+ ## Build and Publish
767
+
768
+ ```bash
769
+ pnpm build
770
+ pnpm build:tsup
771
+ python3 publish.py --dry-run
772
+ ```
773
+
774
+ Publish after npm login:
775
+
776
+ ```bash
777
+ python3 publish.py --publish --registry https://registry.npmjs.org/
778
+ ```
779
+
780
+ The publish script validates lint, typecheck, tests, coverage, build output, ESM imports, CJS requires, package exports, absence of sourcemaps, absence of `dist/node_modules`, and absence of package tarball residue.
781
+
782
+ Published npm files are limited to `dist` and package metadata. Source files, tests, sourcemaps, and temporary tarballs are not published.
@@ -1 +1 @@
1
- "use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e="0.0.5",r={version:e};exports.default=r,exports.version=e;
1
+ "use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e="0.0.6",r={version:e};exports.default=r,exports.version=e;
@@ -1 +1 @@
1
- var a="0.0.5",e={version:a};export{e as default,a as version};
1
+ var a="0.0.6",e={version:a};export{e as default,a as version};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lark.js/sentry",
3
- "version": "0.0.5",
3
+ "version": "0.0.6",
4
4
  "description": "sentry sdk",
5
5
  "type": "module",
6
6
  "keywords": [
@@ -14,7 +14,7 @@
14
14
  "types": "./dist/index.d.ts",
15
15
  "files": [
16
16
  "dist",
17
- "../README.md"
17
+ "./README.md"
18
18
  ],
19
19
  "exports": {
20
20
  ".": {