نشر تطبيقات Tanstack Start React على Cloudflare Pages عبر GitHub Actions: دليل هندسي

شفافية المحتوى: تم توليد وتنسيق هذا المقال آلياً عبر محرك Siwane AI لتقديم محتوى تقني دقيق، مباشر.

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

---

فهم بيئة النشر

يتطلب نشر تطبيقات الويب الحديثة فهمًا دقيقًا لبيئة البناء والنشر. تطبيقات Tanstack Start، كونها إطار عمل ميتا (meta-framework)، توفر مرونة كبيرة ولكنها تتطلب تكوينًا خاصًا عند النشر على منصات مثل Cloudflare Pages.

خصائص Tanstack Start

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

متطلبات Cloudflare Pages

تتطلب Cloudflare Pages أمرين رئيسيين لعملية النشر: أمر البناء (Build Command) ودليل الإخراج (Output Directory). يجب أن يقوم أمر البناء بتجميع التطبيق، وأن يحتوي دليل الإخراج على جميع الأصول الثابتة (HTML، CSS، JS، صور) التي سيتم عرضها.

معلومة!
تستخدم Cloudflare Pages بشكل افتراضي Node.js v18.17.1. تأكد من أن بيئة البناء الخاصة بك في GitHub Actions تتطابق مع هذا الإصدار أو إصدار متوافق.

---

تشخيص مشاكل النشر الشائعة

تنشأ معظم مشاكل النشر من عدم التوافق بين مخرجات عملية بناء Tanstack Start وتوقعات Cloudflare Pages.

أخطاء أمر البناء

الخطأ الأكثر شيوعًا هو استخدام أمر بناء غير صحيح أو غير مكتمل. يجب أن يتضمن الأمر عادةً تثبيت التبعيات ثم تشغيل نص البناء.

npm run build
npm install && npm run build

مسار الإخراج غير الصحيح

عادةً ما تقوم Tanstack Start بإنشاء ملفات البناء في دليل مثل .output/client أو dist. إذا لم يتم تحديد هذا المسار بشكل صحيح في إعدادات Cloudflare Pages، فلن تتمكن المنصة من العثور على الأصول لنشرها.

تحذير!
فشل تحديد دليل الإخراج الصحيح سيؤدي إلى ظهور خطأ "لا توجد ملفات قابلة للنشر" أو صفحة فارغة بعد النشر.

مشاكل بيئة GitHub Actions

قد تنشأ مشاكل من عدم توفر إصدار Node.js الصحيح، أو عدم وجود متغيرات البيئة اللازمة، أو أخطاء في تكوين ملف سير العمل (workflow file) الخاص بـ GitHub Actions.

---

حلول عملية وتكوينات مقترحة

لحل هذه المشاكل، يجب تكوين كل من Cloudflare Pages و GitHub Actions بشكل صحيح.

تكوين Cloudflare Pages

1. أمر البناء (Build Command): قم بتعيينه إلى npm install && npm run build.
2. دليل الإخراج (Build Output Directory): قم بتعيينه إلى .output/client (هذا هو المسار الافتراضي الشائع لـ Tanstack Start للأصول الثابتة). قد تحتاج إلى التحقق من ملف vite.config.ts أو start.config.ts الخاص بك للتأكد من مسار الإخراج الفعلي.
3. إصدار Node.js: تأكد من أن مشروعك متوافق مع إصدار Node.js الافتراضي لـ Cloudflare Pages أو حدد إصدارًا متوافقًا.

ملف GitHub Actions Workflow

استخدم ملف سير عمل مشابه لما يلي في .github/workflows/deploy.yml. هذا المثال يستخدم Wrangler CLI للنشر، مما يوفر تحكمًا أكبر.

name: Deploy Tanstack Start to Cloudflare Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20' # استخدم إصدار Node.js متوافقًا

      - name: Install dependencies
        run: npm install

      - name: Build Tanstack Start app
        run: npm run build

      - name: Publish to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          projectName: اسم-مشروعك-على-Cloudflare
          directory: .output/client # تأكد من هذا المسار
          branch: main
          # gitHubToken: ${{ secrets.GITHUB_TOKEN }} # اختياري، إذا كنت تستخدم Cloudflare Pages مع GitHub Integration

ملاحظة هامة!
تأكد من إضافة CLOUDFLARE_API_TOKEN و CLOUDFLARE_ACCOUNT_ID كمتغيرات سرية (secrets) في مستودع GitHub الخاص بك. يمكنك إنشاء رمز API من لوحة تحكم Cloudflare.

تعديلات على Tanstack Start

في بعض الحالات، قد تحتاج إلى تعديل ملف vite.config.ts أو start.config.ts لضمان أن عملية البناء تنتج مخرجات مناسبة لـ Cloudflare Pages. على سبيل المثال، التأكد من أن المخرجات الثابتة يتم تجميعها في الدليل المتوقع.

import { defineConfig } from '@tanstack/start/vite'
import { TanStackRouterVite } from '@tanstack/router-vite-plugin'

export default defineConfig({
  plugins: [
    TanStackRouterVite(),
  ],
  build: {
    outDir: '.output/client', // تأكد من أن هذا هو دليل الإخراج للعميل
  },
})

هذا يضمن أن Vite، الذي تستخدمه Tanstack Start، يقوم بإخراج ملفات العميل في المسار الصحيح.

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

المشاركات ذات الصلة

المقال الأصلي:
نشر تطبيقات Tanstack Start React على Cloudflare Pages عبر GitHub Actions: دليل هندسي
المصدر: صوان محور XYZ
شكر خاص لـ GEMINI و جمال الحزازي.