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

مقدمة

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

onConnMessage@https://app.example.com/assets/index-Cr8GYWvZ.js:10:14780

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

أكمِل تثبيت React أولاً. يتطلّب تعيين الإصدار (release) الحزمة @lerix-dev/lerix-core بالإصدار 1.1.0 أو أحدث.

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

Vite
Create React App

ولّد خرائط مصدر مخفية في vite.config:

vite.config.ts

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

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

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

يولّد Create React App خرائط المصدر افتراضياً، ما لم تعيّن GENERATE_SOURCEMAP=false. مجلد المخرجات هو build.

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

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

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

افتح مشروعك في لوحة تحكم Lerix.
اذهب إلى Project settings ← API keys.
أنشئ مفتاحاً بصلاحية Upload source maps (أو Full access).

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

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

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

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 يشغّلها بعد كل بناء:

npm install --save-dev @lerix-dev/lerix-cli

package.json

"scripts": {
  "build": "vite build",
  "postbuild": "lerix upload --optional"
}

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

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

الخيارات

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

الخيار	متغير البيئة	الوصف
`--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:

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 الذي كان يظهر سابقاً لتطبيقات الويب.

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

مثال: GitHub Actions

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

.github/workflows/deploy.yml

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.

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

<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)، لذا ارفع الخرائط مجدداً بعد كل بناء.

البدء

أطر العمل

الوحدات

المطورون

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

مقدمة

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

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

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

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

الخيارات

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

مثال: GitHub Actions

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

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

​مقدمة

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

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

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

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

​الخيارات

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

​مثال: GitHub Actions

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

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

مقدمة

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

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

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

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

الخيارات

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

مثال: GitHub Actions

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

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