> ## 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.

# React — خرائط المصدر

> ارفع خرائط المصدر لبناء الإنتاج بشكل خاص ليعرض Lerix أخطاء React في الملف والسطر الأصليين.

## مقدمة

تكون بناءات React للإنتاج مُصغَّرة (minified)، لذا يبدو تتبّع المكدس
(stack trace) القادم من مستخدم حقيقي هكذا:

```text theme={"dark"}
onConnMessage@https://app.example.com/assets/index-Cr8GYWvZ.js:10:14780
```

عندما ترفع خرائط المصدر (source maps) الخاصة ببنائك إلى Lerix، تعيد لوحة
التحكم كل إطار إلى كودك الأصلي، مثل `src/components/Chat.tsx:142`، وتعرض
الأسطر المحيطة به.

تُرفَع الخرائط بشكل خاص وتُحذف من مخرجات البناء قبل النشر. لا تُقدَّم علناً
أبداً، لذا يبقى كودك المصدري خاصاً.

<Note>
  أكمِل [تثبيت React](/ar/frameworks/react/installation) أولاً. يتطلّب تعيين
  الإصدار (release) الحزمة `@lerix-dev/lerix-core` بالإصدار 1.1.0 أو أحدث.
</Note>

## 1. فعّل خرائط المصدر

<Tabs>
  <Tab title="Vite">
    ولّد خرائط مصدر مخفية في `vite.config`:

    ```ts vite.config.ts theme={"dark"}
    import { defineConfig } from 'vite';
    import react from '@vitejs/plugin-react';

    export default defineConfig({
      plugins: [react()],
      build: {
        sourcemap: 'hidden',
      },
    });
    ```

    يولّد الخيار `'hidden'` ملفات `.map` دون إضافة تعليق
    `//# sourceMappingURL` إلى ملفات JavaScript المنشورة، فلا يحاول المتصفح
    تحميلها أبداً. مجلد المخرجات هو `dist`.
  </Tab>

  <Tab title="Create React App">
    يولّد Create React App خرائط المصدر افتراضياً، ما لم تعيّن
    `GENERATE_SOURCEMAP=false`. مجلد المخرجات هو `build`.
  </Tab>
</Tabs>

شغّل بناء الإنتاج وتأكّد من ظهور ملفات `.js.map` بجانب الحزم.

## 2. أنشئ مفتاح API خاصاً

يحتاج رفع خرائط المصدر إلى مفتاح خاص، منفصل عن مفتاح المشروع العام الذي
يستخدمه تطبيقك.

1. افتح مشروعك في [لوحة تحكم Lerix](https://app.lerix.dev).
2. اذهب إلى **Project settings** ← **API keys**.
3. أنشئ مفتاحاً بصلاحية **Upload source maps** (أو **Full access**).

<Warning>
  هذا المفتاح سرّي. خزّنه كسرّ (secret) في نظام CI ولا تضعه أبداً في كود
  العميل ولا ترفعه إلى مستودعك.
</Warning>

## 3. ارفع الخرائط بعد كل بناء

بعد البناء وقبل النشر، شغّل أداة Lerix CLI على مخرجات البناء:

```bash theme={"dark"}
npx @lerix-dev/lerix-cli upload
```

شغّلها من مجلد مشروعك. تجد الأداة مخرجات البناء تلقائياً
(`dist` (Vite) أو `build` (Create React App)) وتستخدم `version` من `package.json` كإصدار. ولتحديدهما بنفسك:
`npx @lerix-dev/lerix-cli upload dist --release 1.4.0`.

ترفع الأداة كل ملف `*.js.map` في المجلد (وتتجاهل `node_modules` وخرائط CSS)،
ثم تحذف ملفات `.map` من مخرجات البناء كي لا تُنشر أبداً. إذا فشل أي رفع،
تُبقي الأداة الخرائط وتخرج بالرمز 1، لتتمكّن من إعادة الخطوة. تتطلّب الأداة
Node.js بالإصدار 18.17 أو أحدث.

### الرفع مع كل بناء

بدلاً من تشغيل الأمر بنفسك، ثبّت الأداة في مشروعك واجعل npm يشغّلها بعد كل
بناء:

```bash theme={"dark"}
npm install --save-dev @lerix-dev/lerix-cli
```

```json package.json theme={"dark"}
"scripts": {
  "build": "vite build",
  "postbuild": "lerix upload --optional"
}
```

الآن كل `npm run build` يرفع الخرائط. الخيار `--optional` يُبقي البناء المحلي
يعمل: على جهاز لا يحوي `LERIX_SECRET_KEY` (جهاز المطوّر)، يُتخطّى الرفع بدلاً
من إفشال البناء، مع حذف ملفات `.map` كالمعتاد. عيّن المفاتيح في نظام الـ CI أو
خادم البناء حيث يُنفَّذ بناء الإنتاج.

<Note>
  لا يشغّل pnpm ولا Yarn 2+ سكربتات `postbuild`. اربط الأمر بدلاً من ذلك:
  `"build": "vite build && lerix upload --optional"`.
</Note>

### الخيارات

يمكن تعيين كل خيار أيضاً عبر متغير بيئة.

| الخيار | متغير البيئة | الوصف |
| - | - | - |
| `--release` | `LERIX_RELEASE` | الإصدار الذي يُنشر به هذا البناء. الافتراضي هو `version` في `package.json`. مرّر القيمة نفسها إلى الـ SDK (راجع الخطوة 4) |
| `--api-key` | `LERIX_API_KEY` | مفتاح API العام المعتاد لمشروعك |
| `--project-id` | `LERIX_PROJECT_ID` | معرّف مشروعك |
| `--secret-key` | `LERIX_SECRET_KEY` | المفتاح الخاص من الخطوة 2 |
| `--url` | `LERIX_URL` | رابط Lerix API. القيمة الافتراضية `https://api.lerix.dev/v1` |
| `--keep-maps` | | إبقاء ملفات `.map` في مخرجات البناء بدلاً من حذفها |
| `--dry-run` | | عرض الخرائط التي سترفع دون رفع أي شيء |
| `--optional` | | تخطّي الرفع بدلاً من الفشل عند عدم تعيين المفاتيح (البناء المحلي). تُحذف ملفات `.map` مع ذلك |

## 4. مرّر الإصدار نفسه إلى الـ SDK

عيّن `release` في خيارات `LerixProvider` إلى القيمة التي مرّرتها إلى
`--release`:

```tsx theme={"dark"}
import { LerixProvider } from '@lerix-dev/lerix-react';

<LerixProvider
  options={{
    apiKey: 'your-api-key',
    projectId: 'your-project-id',
    release: '1.4.0',
  }}
>
  <App />
</LerixProvider>
```

يطابق Lerix الخرائط حسب اسم ملف السكربت. أسماء الأجزاء (chunks) التي يولّدها
الـ bundler مشتقّة من محتواها (content-hashed)، لذا فهي فريدة لكل بناء،
ويفضّل Lerix الخرائط من الإصدار نفسه. تظل المطابقة تعمل إذا حذفت `release`،
لكن يُنصح بتعيينه. كما يحلّ الإصدار محلّ رقم الإصدار `0.0.0` الذي كان يظهر
سابقاً لتطبيقات الويب.

<Tip>
  استخدم القيمة نفسها في الموضعين دون تعديلها يدوياً: معرّف commit في git أو
  قيمة `version` من `package.json` كلاهما خيار جيد.
</Tip>

## مثال: GitHub Actions

يبني سير العمل هذا تطبيق Vite، ثم يرفع الخرائط، ثم ينشر. أضِف
`LERIX_API_KEY` و`LERIX_PROJECT_ID` و`LERIX_SECRET_KEY` كأسرار (secrets) في
المستودع.

```yaml .github/workflows/deploy.yml theme={"dark"}
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      LERIX_RELEASE: ${{ github.sha }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci

      # Make the same release available to the app at build time
      - run: npm run build
        env:
          VITE_LERIX_RELEASE: ${{ github.sha }}

      - run: npx @lerix-dev/lerix-cli upload
        env:
          LERIX_API_KEY: ${{ secrets.LERIX_API_KEY }}
          LERIX_PROJECT_ID: ${{ secrets.LERIX_PROJECT_ID }}
          LERIX_SECRET_KEY: ${{ secrets.LERIX_SECRET_KEY }}

      # Deploy dist here. It no longer contains .map files.
```

ثم اقرأ القيمة في تطبيقك:

```tsx theme={"dark"}
<LerixProvider
  options={{
    apiKey: 'your-api-key',
    projectId: 'your-project-id',
    release: import.meta.env.VITE_LERIX_RELEASE,
  }}
>
```

مع Create React App، سمِّ المتغير `REACT_APP_LERIX_RELEASE` واقرأه من
`process.env.REACT_APP_LERIX_RELEASE` بدلاً من ذلك.

## ما تراه في لوحة التحكم

تعرض الأخطاء الجديدة الملف والسطر والدالة الأصلية، مع الكود المحيط. انقر
**Show minified** لرؤية المكدس كما أرسله المتصفح تماماً. يتلقّى المساعد الذكي
وقضايا GitHub وخادم MCP جميعهم المكدس المقروء أيضاً.

* لا تُحوَّل إلا الأخطاء المُبلَّغ عنها بعد رفع الخرائط. تبقى الأخطاء الأقدم
  بمكدسها المُصغَّر.
* يحتفظ Lerix بأحدث 5,000 خريطة لكل مشروع.
* الحد الأقصى لحجم الخريطة الواحدة 50 MB.

## استكشاف الأخطاء وإصلاحها

| المشكلة | الحل |
| - | - |
| `no .js.map files found` | خرائط المصدر غير مفعّلة لبناء الإنتاج. راجع الخطوة 1 وتأكّد من توجيه الأداة إلى مجلد المخرجات الصحيح. |
| `Uploading source maps needs a private API key...` (`SOURCE_MAP_SECRET_KEY_MISSING`) | الخيار `--secret-key` مفقود أو غير صالح. أنشئ مفتاحاً خاصاً كما في الخطوة 2. |
| `PROJECT_API_KEY_DONT_HAVE_PERMISSION` | المفتاح الخاص لا يملك صلاحية **Upload source maps**. عدّل المفتاح أو أنشئ مفتاحاً جديداً بهذه الصلاحية. |
| لا يزال المكدس مُصغَّراً | تأكّد من تطابق `release` في الـ SDK مع `--release`، ومن رفع خرائط هذا البناء بالتحديد، ومن أن الخطأ جديد. كل إعادة بناء تغيّر بصمات الأجزاء (chunk hashes)، لذا ارفع الخرائط مجدداً بعد كل بناء. |


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