دليل React مع AllStak

التثبيت

ثبّت الحزمة من npm.

npm install @allstak/react

الإعداد

غلّف تطبيقك بـ AllStakProvider ومرّر مفتاح API لمشروعك.

import { AllStakProvider } from '@allstak/react';

export function App() {
  return (
    <AllStakProvider
      apiKey={import.meta.env.VITE_ALLSTAK_API_KEY}
      environment={import.meta.env.MODE}
      release={import.meta.env.VITE_ALLSTAK_RELEASE}
      service="web"
    >
      <AppRoot />
    </AllStakProvider>
  );
}

مثال أساسي

التقط الأخطاء يدويًا عبر كائن AllStak أو خطّاف useAllStak.

import { AllStak, useAllStak } from '@allstak/react';

AllStak.captureMessage('cart opened', 'info');
AllStak.captureException(new Error('checkout failed'));
AllStak.setUser({ id: 'user_123', email: '[email protected]' });

function CheckoutButton() {
  const { captureException } = useAllStak();
  return <button onClick={() => captureException(new Error('failed'))}>Pay</button>;
}

التقاط الأخطاء

اربط معالج أخطاء React من AllStak بـ createRoot لالتقاط أخطاء العرض (تصدّر الحزمة أيضًا AllStakErrorBoundary).

import { createRoot } from 'react-dom/client';
import * as AllStak from '@allstak/react';

createRoot(document.getElementById('root')!, {
  onUncaughtError: AllStak.reactErrorHandler(),
  onCaughtError: AllStak.reactErrorHandler(),
  onRecoverableError: AllStak.reactErrorHandler(),
}).render(<App />);

تتبّع الطلبات

التتبّع الموزّع مفعّل افتراضيًا (enableDistributedTracing): تحقن الحزمة ترويسة traceparent بمعيار W3C وتُصدِر span من نوع http.client لكل طلب صادر، دون أي شيفرة لكل نداء ودون التقاط الأجسام. فعّل enableHttpTracking لتفعيل التقاط أجسام الطلب/الاستجابة.

أفضل الممارسات

• احتفظ بمفتاح API في متغيّر بيئة (مثل VITE_ALLSTAK_API_KEY) لا في الشيفرة.
• اضبط release و service على المزوّد لتُجمَّع الأخطاء لكل نشر.
• يتحكّم tracesSampleRate (0–1) في أخذ عيّنات الـ spans؛ و enableHttpTracking اختياري لالتقاط الأجسام.