> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerix.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js — تتبع الأخطاء

> أبلغ عن الأخطاء والتقط الاستثناءات غير الملتقطة تلقائياً من تطبيق Next.js الخاص بك إلى لوحة تحكم Lerix.

## مقدمة

يلتقط Lerix الأخطاء من تطبيق Next.js الخاص بك لتتمكّن من تصحيح المشاكل
بشكل أسرع. بعد إتمام [تثبيت Next.js](/ar/frameworks/nextjs/installation)،
استخدم `useLerix().throwError()` لإرسال أخطاء مخصّصة إلى لوحة التحكم — أما
الأخطاء غير الملتقطة فتُلتقط تلقائياً، دون الحاجة لأي كود إضافي.

<Note>
  تأكّد من أن تطبيقك مغلّف بـ `LerixNextProvider` قبل الإبلاغ عن الأخطاء.
</Note>

## الإبلاغ عن خطأ

```tsx theme={"dark"}
'use client';
import { useLerix, BugSeverity } from '@lerix-dev/lerix-nextjs';

export function MyComponent() {
  const lerix = useLerix();

  const onSomethingFailed = async () => {
    try {
      await riskyOperation();
    } catch (error) {
      lerix.throwError(
        String(error),
        undefined,
        undefined,
        BugSeverity.HIGH,
        { userId: '123', action: 'payment', amount: 100 },
      );
    }
  };
}
```

### المعاملات (Parameters)

| المعامل | النوع | مطلوب | الوصف |
| - | - | - | - |
| `issue` | `string` | نعم | رسالة الخطأ أو وصفه |
| `stack` | `string[]` | لا | أطر تتبّع المكدس. إذا حُذف، يُلتقط تلقائياً من موضع الاستدعاء — راجع [الالتقاط التلقائي لتتبّع المكدس](#الالتقاط-التلقائي-لتتبع-المكدس) أدناه |
| `type` | `BugType` | لا | تصنيف نوع الخطأ (الافتراضي: `RUNTIME_ERROR`) |
| `severity` | `BugSeverity` | لا | مستوى الخطورة (الافتراضي: `MEDIUM`) |
| `metadata` | `Record<string, unknown>` | لا | سياق إضافي يُرفق بالتقرير |

### قيم `BugType`

| القيمة | الوصف |
| - | - |
| `RUNTIME_ERROR` | استثناء غير معالَج يُرمى أثناء التشغيل |
| `LOGIC_BUG` | سلوك غير صحيح لا يرمي استثناءً |
| `UI_BUG` | خلل بصري أو في التخطيط (layout) |
| `NETWORK_ERROR` | طلب شبكة فاشل أو مُشوَّه |
| `PERFORMANCE` | بطء، تقطّع (jank)، أو استهلاك موارد مفرط |
| `COMPATIBILITY` | خلل يظهر على متصفّح أو جهاز محدّد |
| `VALIDATION_ERROR` | إدخال غير صالح تجاوز التحقق رغم أنه لا ينبغي |
| `SECURITY` | خلل متعلّق بالأمان |
| `CRASH` | توقّف التطبيق بشكل غير متوقّع |
| `UNKNOWN` | لا شيء مما سبق |

### قيم `BugSeverity`

| القيمة | الوصف |
| - | - |
| `CRITICAL` | يعطّل وظيفة أساسية أو يؤثّر على جميع المستخدمين |
| `HIGH` | تأثير كبير، لكن يوجد حل بديل (workaround) |
| `MEDIUM` | ملحوظ لكن تأثيره محدود |
| `LOW` | بسيط أو شكلي |
| `UNKNOWN` | لم يتم تقييم الخطورة بعد |

## الالتقاط التلقائي للأخطاء

يُثبّت `LerixNextProvider` التقاط الأخطاء بطريقتين، بحيث لا حاجة لتغليف أي شيء في `try`/`catch` للحصول على تغطية أساسية:

* يلتقط `LerixErrorBoundary` الأخطاء التي تحدث أثناء العرض (rendering) — عقد حدود الأخطاء في React يغطّي فقط مرحلة العرض، وليس معالجات الأحداث أو الكود غير المتزامن.
* تلتقط مستمعا `window.onerror` وَ `unhandledrejection` العامّان كل شيء آخر.

لتعطيل المستمعَين العامَّين (يستمر `LerixErrorBoundary` في التقاط أخطاء العرض بغضّ النظر عن هذا الخيار):

```tsx theme={"dark"}
<LerixNextProvider options={{ enableCrashReporting: false }}>
```

### حدود الأخطاء الخاصة بـ Next.js

يلتقط `LerixErrorBoundary` فقط الأخطاء الواقعة تحت المكان الذي وضعته فيه.
بالنسبة للأخطاء الأعلى من ذلك — وأبرزها في التخطيط الجذري (root layout)
نفسه — يتطلّب Next.js حدود أخطاء خاصة به قائمة على الملفات (`error.tsx`،
`global-error.tsx`). استدعِ `reportCaughtError` مباشرة داخل هذه الملفات
بدلاً من ذلك:

```tsx app/error.tsx theme={"dark"}
'use client';
import { reportCaughtError } from '@lerix-dev/lerix-nextjs';
import { useEffect } from 'react';

export default function Error({ error }: { error: Error }) {
  useEffect(() => {
    reportCaughtError(error);
  }, [error]);

  return <p>Something went wrong.</p>;
}
```

## الالتقاط التلقائي لتتبّع المكدس

عند استدعاء `throwError()` دون تمرير معامل `stack`، يُلتقط تتبّع مكدس
تلقائياً من موضع الاستدعاء — لا تحتاج لتمريره صراحةً إلا عند الإبلاغ عن
تتبّع مكدس خطأ (`Error`) ملتقَط بنفسك بدلاً من موضع استدعاء `throwError`.

في الحالتين، يُحلَّل كل إطار من إطارات المكدس من موضعه المُجمَّع إلى ملف
المصدر الأصلي وسطره، باستخدام خريطة المصدر الخاصة بالبناء نفسه — بما في
ذلك صيغة خريطة المصدر المُقسَّمة (sectioned) الخاصة بـ Turbopack. يحدث هذا
تلقائياً؛ لا حاجة لأي إعداد.

<Note>
  يتطلّب التحليل أن تكون خريطة المصدر متاحة على رابط الإطار — وهذا صحيح
  دائماً في بيئة التطوير، وصحيح في الإنتاج فقط إذا كان بناؤك يقدّم ملفات
  `.map` علناً. إذا أبقى بناء الإنتاج خرائط المصدر خاصة، ترجع الإطارات إلى
  موضعها المُجمَّع بدلاً من فشل الإبلاغ.
</Note>

<Tip>
  لتحصل على تتبّعات مكدس مقروءة في الإنتاج مع إبقاء خرائط المصدر خاصة،
  ارفعها إلى Lerix بعد كل بناء. راجع
  [خرائط المصدر لـ Next.js](/ar/frameworks/nextjs/source-maps).
</Tip>

### تحقّق من التكامل

```tsx theme={"dark"}
lerix.throwError('Test error');
```

ثم افتح [لوحة التحكم](https://app.lerix.dev) — يجب أن يظهر الخطأ خلال ثوانٍ، مع تتبّع مكدس محلَّل يشير إلى هذا السطر بالتحديد.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.