حل مشكلة نشر تطبيق Tanstack Start React على Cloudflare باستخدام GitHub Actions.

تم توليد هذا المقال عبر أدوات الذكاء الاصطناعي (إصدار 4.0) لتقديم إجابة تقنية دقيقة ومباشرة.

في عالم تطوير الويب الحديث، أصبحت أطر العمل مثل Tanstack Start React خيارًا شائعًا لبناء تطبيقات ويب قوية وذات أداء عالٍ. ومع ذلك، قد يواجه المطورون تحديات عند محاولة نشر هذه التطبيقات على منصات الاستضافة السحابية مثل Cloudflare Pages، خاصة عند استخدام مسارات التكامل المستمر/النشر المستمر (CI/CD) عبر GitHub Actions. يهدف هذا المقال إلى تقديم تحليل هندسي شامل لهذه المشكلات وحلول عملية لتجاوزها.

---

تنشأ المشكلات عادةً من عدة أسباب جذرية، أبرزها تعارضات بيئة البناء، الإعدادات غير الصحيحة لـ Cloudflare Pages، ومتطلبات وقت التشغيل الخاصة بـ Tanstack Start React. غالبًا ما تفشل عمليات البناء بسبب عدم تطابق إصدارات Node.js، أو استخدام مدير حزم خاطئ (مثل npm بدلاً من pnpm أو yarn)، أو عدم توفر الذاكرة الكافية أثناء عملية البناء المعقدة.

على سبيل المثال، قد تقوم Cloudflare Pages بتوفير بيئة بناء افتراضية لا تتوافق تمامًا مع متطلبات Tanstack Start، مما يؤدي إلى أخطاء مثل "command not found" أو "out of memory". كما أن عدم تحديد مجلد الإخراج الصحيح أو أمر البناء الدقيق يمكن أن يمنع Cloudflare Pages من اكتشاف الأصول المبنية بشكل صحيح.

---

لحل هذه المشكلات، يجب تبني نهج هندسي دقيق يتضمن تعديلات على ملفات GitHub Actions workflow وتكوينات Cloudflare Pages. الحل العملي يرتكز على ضمان بيئة بناء متسقة ومحددة، وتوجيه Cloudflare Pages بشكل صحيح.

1. تحديد بيئة البناء في GitHub Actions:

   يجب تحديد إصدار Node.js و pnpm (إذا كان مشروعك يستخدمه) بشكل صريح في ملف workflow الخاص بـ GitHub Actions لضمان التوافق.

   name: Deploy Tanstack Start to Cloudflare Pages
   
   on:
     push:
       branches:
         - main
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout project
           uses: actions/checkout@v4
   
         - name: Setup Node.js
           uses: actions/setup-node@v4
           with:
             node-version: '20' # استخدم إصدار Node.js الموصى به لمشروعك
   
         - name: Install pnpm
           uses: pnpm/action-setup@v3
           with:
             version: 8 # تأكد من تثبيت pnpm إذا كان مشروعك يستخدمه
             run_install: false
   
         - name: Get pnpm store directory
           shell: bash
           run: |
             echo "PNPM_CACHE_DIR=$(pnpm store path)" >> $GITHUB_ENV
   
         - uses: actions/cache@v4
           name: Setup pnpm cache
           with:
             path: ${{ env.PNPM_CACHE_DIR }}
             key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
             restore-keys: |
               ${{ runner.os }}-pnpm-
   
         - name: Install dependencies
           run: pnpm install --frozen-lockfile
   
         - name: Build project
           run: pnpm run build # أمر البناء الخاص بـ Tanstack Start
   
         - name: Deploy to Cloudflare Pages
           uses: cloudflare/pages-action@v1
           with:
             apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
             accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
             projectName: your-tanstack-start-app # اسم مشروعك في Cloudflare Pages
             directory: dist # مجلد الإخراج الافتراضي لـ Tanstack Start
             gitHubToken: ${{ secrets.GITHUB_TOKEN }}
             branch: main
             # إذا كان تطبيقك يستخدم SSR أو API Routes، قد تحتاج إلى Cloudflare Workers
             # في هذه الحالة، تأكد من أن بنية مشروعك تدعم ذلك وأن Cloudflare Pages
             # مُعدّة لاستخدام Workers (Functions) بشكل صحيح.
   

2. تكوين Cloudflare Pages:

   في لوحة تحكم Cloudflare Pages، تأكد من أن الإعدادات التالية صحيحة:

   • Build command: pnpm run build (أو npm run build، yarn build حسب مدير الحزم المستخدم).
   • Build output directory: dist (هذا هو المجلد الافتراضي الذي ينتج عن عملية بناء Tanstack Start).
   • Framework preset: اختر "Other" أو "React". في بعض الحالات، قد يكون "Other" أكثر مرونة.
   • Environment Variables: أضف أي متغيرات بيئة ضرورية لعملية البناء أو وقت التشغيل (مثل NODE_ENV=production).
3. تعديلات بنية المشروع (إذا لزم الأمر):

   تأكد من أن ملف package.json يحتوي على سكربت بناء صحيح، مثل "build": "start build". إذا كان Tanstack Start يستخدم ميزات تتطلب بيئة Node.js في وقت التشغيل (مثل SSR أو API Routes)، يجب التأكد من أن Cloudflare Pages مُعدّة لاستخدام Cloudflare Workers (Functions) للتعامل مع هذه الطلبات. يتطلب هذا عادةً بنية مشروع محددة حيث يتم تجميع وظائف Worker بشكل منفصل أو ضمن إعدادات Tanstack Start.

ملاحظة هامة: إذا كان تطبيق Tanstack Start الخاص بك يعتمد بشكل كبير على SSR أو API Routes، فقد تحتاج إلى دمج Cloudflare Workers (Functions) مع Cloudflare Pages. يتطلب هذا عادةً تكوينًا إضافيًا في مشروعك لإنشاء وظائف Worker من مسارات API الخاصة بك، وتوجيه Cloudflare Pages لاستخدامها.

---

باتباع هذه الخطوات، يمكن للمطورين التغلب على التحديات الشائعة لنشر تطبيقات Tanstack Start React على Cloudflare Pages بنجاح. التركيز على تحديد بيئة بناء متسقة، وتكوين صحيح لمنصة الاستضافة، وفهم متطلبات وقت التشغيل للتطبيق، هو مفتاح النشر الناجح.

---

لماذا يفشل بناء تطبيقي على Cloudflare Pages مع خطأ "Out of Memory"؟

غالبًا ما يحدث هذا بسبب استهلاك عملية البناء لكمية كبيرة من الذاكرة، خاصة في المشاريع الكبيرة أو التي تستخدم أدوات بناء معقدة. يمكن التخفيف من ذلك عن طريق تحسين عملية البناء، أو استخدام ذاكرة تخزين مؤقت (cache) لمدير الحزم (مثل pnpm cache)، أو في بعض الحالات، قد تحتاج إلى استخدام بيئة بناء ذات موارد أعلى إذا كانت Cloudflare Pages توفر خيارات لذلك.

هل يمكنني استخدام Node.js v22 في Cloudflare Pages؟

تعتمد إمكانية استخدام إصدار معين من Node.js على الدعم الذي توفره Cloudflare Pages في بيئة البناء الخاصة بها. يفضل دائمًا التحقق من وثائق Cloudflare Pages لأحدث إصدارات Node.js المدعومة. في GitHub Actions، يمكنك تحديد الإصدار الذي تريده، ولكن يجب أن يكون متوافقًا مع ما تدعمه Cloudflare Pages لتجنب المشاكل في مرحلة النشر.

كيف أتعامل مع متغيرات البيئة في Tanstack Start على Cloudflare Pages؟

يمكنك تعريف متغيرات البيئة في إعدادات مشروعك على Cloudflare Pages ضمن قسم "Environment variables". هذه المتغيرات ستكون متاحة أثناء عملية البناء وفي وقت التشغيل لتطبيقات Workers (Functions). تأكد من أن تطبيق Tanstack Start الخاص بك مصمم لقراءة هذه المتغيرات بشكل صحيح، عادةً من خلال `process.env`.

المصدر:
صوان محور XYZ
شكر خاص لـ GEMINI وجمال الحزازي.