تخطَّ إلى المحتوى

الويب

التثبيت

npm install @heysada/athar

شرح الاستخدام أدناه بالإنجليزية، كما يظهر في سجل الحزمة، والشيفرة نفسها في كل لغة.

Error and crash reporting for the web. It reports uncaught errors and unhandled promise rejections, each with a trail of what the page did before (console, clicks, fetch/XHR, navigation). It counts release health (crash-free sessions and users per release) and takes user feedback on an error. In the panel, issues are grouped, symbolicated with your source maps, and explained in English or Arabic.

It is a thin layer over the official Sentry browser SDK (@sentry/browser, MIT), set up with your app’s Sentry DSN. What it adds is consent, the user’s identity, and settings that keep personal data in the browser.

Use it

import { captureException, identify, init } from "@heysada/athar";

await init({
  dsn: "https://ik_…@in.example.com/ingest/7", // the panel: Apps → your app → its key's DSN
  release: "[email protected]",                    // also given to the CLI when uploading source maps
});
await identify(currentUser?.id ?? null);       // optional: your own opaque id for the user

Call init once, as early as you can. Later, captureException(error) reports an error you caught, captureMessage(text) reports a message, and addBreadcrumb / setTag add context. sendFeedback({ message, eventId }) attaches what the user wrote to that error’s issue.

With a <script> tag, use dist/athar.iife.js. It sets window.AppErrors with the same functions and has the Sentry SDK and the core inside it. The ES module (dist/athar.js) is for a bundler. It imports @sentry/browser and the shared web core as dependencies, so a page that already ships either gets a single copy.

  • CSP: allow connect-src to the DSN’s host.
  • Release health needs release: without it, errors are still sent but no sessions are.
  • Single-page apps: sessions: "route" counts a session per navigation instead of per page load.

Source maps

After vite build (or any bundler that writes .map files), upload the maps with the same release, then leave them off your server:

npx @heysada/athar-cli sourcemaps dist/assets --url-prefix "~/assets" --release [email protected] \
  --url https://in.example.com --app <app id> --key "$DEBUG_FILES_KEY"

The panel then shows the original file, line and function for each frame.

  • Strict mode (requireConsent: true): nothing at all is collected until grant(): no handlers, breadcrumbs, sessions or requests. Until then the Sentry SDK isn’t even started. revoke() stops collection; setEnabled(false) opts this browser out. Both answers are remembered across visits.
  • No personal data is collected: no IP address, cookies, headers, request bodies or query strings. The user is only the id you pass to identify; without one, it’s a random id for this browser, so crash-free users can still be counted. The service also scrubs card numbers, emails and tokens on arrival.
  • It never throws into your page. A bad DSN is a console.warn.