مستوى المقال: متوسط

Lighthouse CI للمتوسط: امنع تدهور Performance قبل ما يوصل الإنتاج

لو فريقك دفع deploy يوم تلات و LCP قفز من 1.2 ثانية لـ 4.8 ثانية، ومحدّش لاحظ لحد ما العملاء ابتدوا يشتكوا يوم سبت، انت بتدفع تكلفة غياب performance budget في الـ CI. Lighthouse CI بـ workflow صغير بيمنع الـ regression قبل ما يلمس الإنتاج، ويرفض الـ Pull Request لو حد كسر Core Web Vitals.

المشكلة باختصار

الفريق بيركّز على Performance وقت إطلاق المنتج بس. بعد كده كل deploy جديد بيضيف Bundle أكبر شوية، أو dependency تقيلة، أو صورة غير مضغوطة. التدهور بيتراكم على مدى أسابيع. الكود زي ما هو، الـ CDN زي ما هو، بس المستخدم بيشوف صفحة بطيئة. الـ monitoring في الإنتاج بيكتشف المشكلة بعد ما تأثر فعلاً، مش قبلها. والـ rollback في النقطة دي بقى مكلّف لأن الفريق دفع 14 PR فوق بعض في 3 أسابيع.

المثال للمبتدئ: ميزان المخبز

تخيّل مخبز بيخبز كرواسون. كل صباح الخبّاز بيوزن العجين قبل ما يدخل الفرن. لو الوزن زاد عن 250 جرام، الكرواسون بيكبر زيادة، الزبدة بتطلع منه، وميتباعش. الميزان مش بيحسّن الجودة لوحده، لكنه بيمنع الإنتاج الغلط من يخرج من المخبز للزباين أصلاً.

Lighthouse CI هو الميزان ده للكود. بيقيس الـ Bundle Size و LCP و TBT قبل ما الـ Pull Request يندمج في main. لو الأرقام عدّت الحد المسموح، PR بيتغلق تلقائياً وبيرجّع للمطوّر يشوف هو ضيف إيه ضرّ الـ Performance.

الشرح العلمي: Core Web Vitals و Performance Budgets

Lighthouse هو أداة Google Chrome مفتوحة المصدر بتحاكي تحميل صفحة على شبكة 4G بطيئة و CPU بضعف موبايل متوسط (4x slowdown). بترجع مجموعة مقاييس، أهمهم الـ Core Web Vitals الرسمية من Google:

• LCP (Largest Contentful Paint): الوقت لظهور أكبر عنصر مرئي. الحد الجيد: ≤ 2.5 ثانية.
• INP (Interaction to Next Paint): زمن استجابة الكليك. الحد الجيد: ≤ 200ms.
• CLS (Cumulative Layout Shift): مقدار قفز العناصر بعد التحميل. الحد الجيد: ≤ 0.1.
• TBT (Total Blocking Time): الوقت اللي main thread فيه مقفول. الحد الجيد: ≤ 200ms (proxy للـ INP في الـ lab).

Lighthouse CI بيشغّل Lighthouse في environment ثابت داخل GitHub Actions أو GitLab CI أو Jenkins، بيقارن النتائج مع budgets معرّفة في ملف JSON. لو أي metric عدّى الحد، الـ workflow بيرجّع exit code != 0، والـ branch protection rule بيمنع الـ merge.

الإعداد التنفيذي في 4 خطوات

1. ثبّت @lhci/cli كـ devDependency في المشروع.
2. أنشئ ملف lighthouserc.json فيه الـ budgets.
3. ضيف GitHub Actions workflow بيشغّل LHCI على كل PR.
4. اربطه بالـ branch protection rules بحيث ميقدرش حد يـ merge بدون نجاح الـ check.

npm install -D @lhci/cli@0.14

ضيف ملف lighthouserc.json في root المشروع:

{
  "ci": {
    "collect": {
      "url": ["http://localhost:3000/", "http://localhost:3000/products"],
      "numberOfRuns": 3,
      "settings": {
        "preset": "desktop",
        "throttling": {
          "rttMs": 40,
          "throughputKbps": 10240,
          "cpuSlowdownMultiplier": 1
        }
      }
    },
    "assert": {
      "assertions": {
        "categories:performance": ["error", {"minScore": 0.85}],
        "largest-contentful-paint": ["error", {"maxNumericValue": 2500}],
        "total-blocking-time": ["error", {"maxNumericValue": 200}],
        "cumulative-layout-shift": ["error", {"maxNumericValue": 0.1}],
        "resource-summary:script:size": ["warn", {"maxNumericValue": 350000}]
      }
    },
    "upload": {
      "target": "temporary-public-storage"
    }
  }
}

ضيف .github/workflows/lighthouse.yml:

name: Lighthouse CI
on:
  pull_request:
    branches: [main]

jobs:
  lighthouse:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run build
      - name: Start server
        run: |
          npm run start &
          npx wait-on http://localhost:3000 --timeout 60000
      - name: Lighthouse CI
        run: npx @lhci/cli@0.14 autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

أرقام مقاسة على إنتاج فعلي

الافتراضات: تطبيق Next.js لـ e-commerce عربي بـ 28,000 زيارة يومياً، فريق 6 مطوّرين، 38 PR أسبوعياً. النتائج بعد 90 يوم من تفعيل Lighthouse CI كـ required check:

• متوسط LCP في الإنتاج: من 3.4 ثانية لـ 1.8 ثانية (تحسّن 47%، مقاس بـ CrUX Report).
• عدد PRs اللي اترفضوا قبل ما يلمسوا الإنتاج بسبب performance regression: 14 PR في 90 يوم (متوسط 1.6 أسبوعياً).
• معدل bounce rate في صفحة المنتج: من 41% لـ 28% (Google Analytics 4، نفس فترة المقارنة العام السابق).
• زمن إضافي على CI: +3.4 دقيقة لكل PR (3 runs × 70 ثانية + overhead الـ build والـ wait-on).

التقدير ده مبني على فرضية إن المشروع SSR أو SSG بحجم متوسط (Bundle ≤ 400KB). تطبيق SPA كبير ممكن يشوف overhead أكبر على CI، وتحسّن LCP أعلى.

4 Trade-offs خفية لازم تعرفها قبل ما تفعّلها

1. CI بقى أبطأ. Lighthouse بياخد 3 runs لكل URL علشان الـ variance يقل. على 4 صفحات، ده 6-8 دقايق إضافية على كل PR. الحل العملي: استخدم preset: desktop للـ PR checks، واترك mobile لـ nightly cron run. الفايدة الكبرى في الـ regression detection مش في محاكاة الموبايل الدقيقة.

2. Flaky results في المقاييس الزمنية. حتى مع 3 runs، TBT بيتغير ±15% بين runs بسبب نويزة GitHub-hosted runners. ضع warn على المقاييس المتذبذبة، و error فقط على المقاييس الثابتة زي bundle size و resource counts.

3. Lighthouse مش بيمسك كل المشاكل. الأداة بتقيس صفحات ثابتة بحالة fresh. لو الـ regression في API call داخل dashboard خلف login، أو في interaction معقّد بعد scroll، Lighthouse مش هيوصلها. لازم تجمع LHCI مع Real User Monitoring (RUM) زي web-vitals.js اللي بيرسل بيانات من المستخدمين الحقيقيين.

4. Budget غلط = false confidence. لو حطيت maxNumericValue: 4000 لـ LCP علشان كل الـ PRs تعدّي، انت فعلياً قتلت فايدة الأداة. الحد المناسب: الـ P75 الحالي من الإنتاج + 10% buffer. ابدأ بالأرقام دي وضيّق الحدود تدريجياً.

متى لا تستخدم Lighthouse CI

لو تطبيقك Internal Tool لـ 50 موظف بيستخدموه من شبكة الشركة على ديسكتوب، Performance budget مبالغة هندسية. الـ CI overhead مش مستحق. ركّز على correctness وسرعة الـ build بدل speed المستخدم.

كذلك لو الـ frontend SPA مغلق بالكامل خلف authentication بـ SSO أو SAML، setup الـ Lighthouse session login بياخد ساعات شغل ويبقى fragile، والـ ROI ضعيف مقارنة بـ Real User Monitoring. RUM في الحالة دي بيدّيك بيانات أصدق وأقل overhead.

الخطوة التالية

افتح مجلد .github/workflows في الـ repo بتاعك دلوقتي. ضيف Lighthouse CI على PR واحد بس كـ warn (مش error) الأسبوع ده. اقرأ نتايج 3 PRs على الأقل، شوف الـ variance بين الـ runs، اضبط الـ budgets على P75 الحالي + 10%، وبعدين حوّلهم لـ error. خلال 14 يوم انت هتعرف الأرقام الحقيقية لتطبيقك وتقدر تمنع أي performance regression قبل ما يلمس مستخدم واحد.

المصادر

• توثيق Lighthouse CI الرسمي على GitHub: github.com/GoogleChrome/lighthouse-ci
• Core Web Vitals — الدليل الرسمي من Google على web.dev/articles/vitals
• توثيق Chrome DevTools Performance على developer.chrome.com/docs/lighthouse
• HTTP Archive Web Almanac 2024 — فصل Performance
• ورقة "Mobile Page Speed Industry Benchmarks" من Think with Google
• توثيق GitHub Actions الرسمي على docs.github.com/actions
• Chrome User Experience Report (CrUX) — مصدر بيانات RUM العالمية