كيف تبني تطبيق PWA محلي: تحويل موقع ويب إلى "تطبيق حقيقي"

1 ما هي PWA وما هو تطوير PWA

في هذا الدرس التعليمي، سنكمل حلقة مغلقة كاملة: من مشروع ويب عادي إلى "تطبيق حقيقي" يمكن تثبيته على سطح المكتب وشاشة رئيسية للهاتف ويعمل أيضًا بدون اتصال. ستقوم شخصيًا بتحويل تطبيق React إلى PWA ونشره عبر الإنترنت وتثبيته على هاتفك للاختبار.

ما سنقوم ببنائه هو تطبيق Tomato Farm - تطبيق PWA يجمع بين تقنية بومودورو ولعبة الزراعة بشكل مثالي. تكسب نقاطًا من خلال 25 دقيقة من العمل المركز، ثم تستخدم هذه النقاط لشراء البذور وزراعة المحاصيل. مع ارتفاع مستواك، تفتح المزيد من الأراضي الزراعية والبذور الأفضل. والأهم من ذلك، أنه يستمر في العمل حتى بدون إنترنت، وجميع البيانات مخزنة محليًا.

لهذا الدرس، يجب أن تمتلك على الأقل:

جهاز كمبيوتر (Windows أو Mac)
بيئة Node.js (الإصدار 18.0 أو أحدث)
مساعد البرمجة بالذكاء الاصطناعي الخاص بك (Cursor / Trae / Claude Code، إلخ)
هاتف (لاختبار التثبيت على الهاتف)

1.1 تعريف PWA

PWA (Progressive Web App) هو نوع خاص من المواقع. من خلال تقنية Service Worker، يكتسب قدرة "التخزين المؤقت والتحكم في نفسه."

لماذا لا يمكن للمواقع العادية العمل بدون اتصال، لكن PWA يمكنها ذلك

الموقع العادي يحتاج إلى تنزيل ملفات HTML وCSS وJS من الخادم في كل مرة يُفتح فيها، لذلك إذا انقطعت الشبكة، ببساطة لا يمكنه التحميل. من ناحية أخرى، PWA يستخدم Service Worker (سكريبت JS يعمل في خلفية المتصفح) لتخزين هذه الملفات محليًا عند الزيارة الأولى. بعد ذلك، حتى لو انقطعت الشبكة، يمكن لـ Service Worker قراءة الملفات مباشرة من ذاكرة التخزين المؤقت المحلية وعرض الصفحة بشكل طبيعي.

تشبيه بسيط: الموقع العادي مثل استعارة كتاب من المكتبة في كل مرة (يجب أن يكون لديك إنترنت)، بينما PWA مثل شراء الكتاب ووضعه على رف كتبك (بعد التنزيل الأول، لا يزال بإمكانك قراءته بدون اتصال).

PWA مقابل الموقع العادي مقابل التطبيق الأصلي

الميزة	الموقع العادي	PWA	التطبيق الأصلي
التثبيت	غير مطلوب	اختياري (إضافة إلى الشاشة الرئيسية)	يجب التنزيل من متجر التطبيقات
الاستخدام بدون اتصال	لا	نعم (بعد التخزين المؤقت)	نعم
طريقة التحديث	تحديث تلقائي	تحديث تلقائي / في الخلفية	تحديث يدوي من المستخدم
الحجم	لا شيء	بضع مئات من الكيلوبايت إلى بضع ميغابايت	عشرات الميغابايت أو أكثر
تكلفة التطوير	منخفضة	منخفضة (قاعدة كود واحدة)	عالية (iOS / Android منفصل)

ملخص بجملة واحدة: PWA هو "صفحة ويب يمكنها تخزين ملفاتها الخاصة" - لديها خفة الموقع (لا حاجة للتثبيت، تحديث تلقائي) وتجربة التطبيق الأصلي (دعم العمل بدون اتصال، قابل للتثبيت على سطح المكتب/الشاشة الرئيسية).

1.2 لماذا تختار PWA؟

في عصر Vibe Coding، PWA هو أحد "الحلول المشتركة بين المنصات" الأكثر فعالية من حيث التكلفة:

بعد المقارنة	التطبيق الأصلي	PWA
تكلفة التطوير	يجب تطوير iOS / Android / سطح المكتب بشكل منفصل	قاعدة كود واحدة لجميع المنصات
التثبيت	يجب الذهاب إلى متجر التطبيقات	التثبيت مباشرة في المتصفح، فوري
طريقة التحديث	يجب على المستخدمين التحديث يدويًا	تحديث تلقائي، غير مرئي للمستخدم
حجم الحزمة	غالبًا عشرات الميغابايت	عادة بضع مئات من الكيلوبايت فقط
دعم العمل بدون اتصال	مدمج بشكل طبيعي	مدعوم من خلال Service Worker
أفضل السيناريوهات	الحاجة إلى وصول عميق للأجهزة (AR / Bluetooth، إلخ)	عرض المحتوى، الأدوات، التطبيقات الخفيفة

ملخص بجملة واحدة: إذا كان تطبيقك لا يحتاج إلى AR عبر الكاميرا أو الوصول لأجهزة Bluetooth، فإن PWA هو الخيار الأسهل تقريبًا.

1.5 خريطة طريق الدرس

لجعل عملية التعلم أقل مللاً، يدور هذا الدرس حول حالة ممتعة وعملية - Tomato Farm. إنها لعبة زراعة بومودورو تجمع بين العمل المركز والمكافآت المحولة إلى لعبة. مع وضع Vibe Coding لمساعدات البرمجة بالذكاء الاصطناعي، سنقسم العملية من الصفر إلى تثبيت الهاتف إلى مسار قابل لإعادة الاستخدام:

بناء الفهم والبيئة: فهم ما هي PWA وتثبيت Node.js ومساعد برمجة بالذكاء الاصطناعي والتأكد من سلاسة سلسلة الأدوات.
بناء هيكل المشروع: إنشاء مشروع React + TypeScript يعمل محليًا.
التطوير التكراري بالذكاء الاصطناعي: من خلال المحادثة مع الذكاء الاصطناعي، بناء عداد بومودورو ونظام الزراعة ونظام المستويات وعرض المحاصيل SVG والمزيد.
تكوين PWA واختبار العمل بدون اتصال: إضافة Service Worker وManifest ثم التحقق من دعم العمل بدون اتصال.
النشر والتثبيت على الهاتف: النشر على Vercel للحصول على عنوان URL بـ HTTPS ثم التثبيت والاستخدام على هاتف.

هذا القسم يعطي الصورة الكبيرة فقط، دون توسيع الأوامر الدقيقة. في الوقت الحالي، فقط تذكر الخط الرئيسي: إعداد البيئة -> بناء الهيكل -> الوصف والتوليد بالذكاء الاصطناعي -> تكوين PWA -> التسليم عبر النشر. في الفصول التالية، سنسير معك في كل خطوة.

2 إعداد بيئة التطوير

2.1 الأدوات المستخدمة في هذا الدرس

خلال عملية التطوير بالكامل نستخدم ثلاث أدوات معًا، وتأخذ كل منها دور "التصميم" و"البناء" و"القبول".

مساعد البرمجة بالذكاء الاصطناعي (Cursor / Trae / Claude Code): هذا هو شريك البرمجة بالذكاء الاصطناعي الخاص بك. في وضع Vibe Coding، لم نعد بحاجة لكتابة الكود سطرًا بسطر. بدلاً من ذلك، نخبر الذكاء الاصطناعي بشكل أساسي بلغة طبيعية بالوظائف التي نريدها، ويتولى هو توليد الكود وتعديله.
Node.js + Vite: هذه هي مصنع بناء المشروع. يوفر Node.js بيئة تشغيل JavaScript، وVite هو أداة بناء أمامية من الجيل التالي بسرعة فائقة، خاصة مناسبة لبناء PWA.
هاتف: يعمل كـ جهاز اختبار للتحقق من نتيجة التشغيل. يمكنك الوصول مباشرة إلى PWA المنشورة في المتصفح على هاتفك واختبار التثبيت الفعلي ووظائف العمل بدون اتصال.

2.2 تثبيت Node.js

Node.js هو البيئة الأساسية لتطوير PWA. قم بزيارة الموقع الرسمي https://nodejs.org وقم بتنزيل إصدار LTS (الدعم طويل الأمد) (هذا الدرس مبني على Node.js 18.x أو أحدث).

بعد التنزيل، ثبته مثل البرنامج العادي بالنقر المزدوج على المثبت والاحتفاظ بالخيارات الافتراضية.

بعد التثبيت، افتح الطرفية (CMD / PowerShell على Windows، Terminal على Mac) وشغّل:

bash

node --version
npm --version

إذا رأيت مخرجات إصدارات مثل v18.17.0 و 9.6.7، فهذا يعني نجاح التثبيت.

2.3 تثبيت مساعد البرمجة بالذكاء الاصطناعي

مساعد البرمجة بالذكاء الاصطناعي هو ساحة المعركة الرئيسية لـ Vibe Coding. يمكنك ببساطة فهمه كـ "محرر مع ذكاء اصطناعي خارق مدمج فيه."

الخيارات الموصى بها:

Trae: قم بزيارة https://www.trae.cn وقم بتنزيل الإصدار المناسب لنظام التشغيل الخاص بك
Cursor: قم بزيارة https://cursor.sh وقم بتثبيته
Claude Code: إذا كنت تستخدم Claude بالفعل، يمكنك استخدام Claude Code مباشرة

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

2.4 إنشاء مشروع جديد

افتح مساعد البرمجة بالذكاء الاصطناعي وأدخل الموجه التالي في مربع المحادثة:

text

Please help me create a React project named tomato-farm-pwa for building a Tomato Farm app.
It needs to support TypeScript, and also include PWA functionality (the kind that can be installed to a phone home screen).

سيقوم الذكاء الاصطناعي تلقائيًا بتنفيذ الخطوات التالية:

الخطوة 1: إنشاء المشروع

bash

npm create vite@latest tomato-farm-pwa -- --template react-ts

الخطوة 2: الدخول إلى المشروع وتثبيت التبعيات

bash

cd tomato-farm-pwa
npm install

الخطوة 3: تثبيت إضافة PWA

bash

npm install vite-plugin-pwa -D

بعد انتهاء الذكاء الاصطناعي، سيبدو هيكل مشروعك تقريبًا هكذا:

text

tomato-farm-pwa/
├── public/              # الأصول الثابتة (الأيقونات، مواد SVG توضع هنا)
├── src/
│   ├── App.tsx          # المكون الرئيسي
│   ├── main.tsx         # ملف الدخول
│   └── App.css          # الأنماط
├── index.html           # ملف HTML للدخول
├── vite.config.ts       # تكوين Vite (تكوين PWA يوضع هنا)
├── package.json
└── tsconfig.json

2.5 فهم هيكل المشروع

بعد إنشاء المشروع، نحتاج إلى فهم دور عدة ملفات رئيسية:

الملف / الدليل	الغرض
`src/App.tsx`	مكون التطبيق الرئيسي، حيث يُكتب منطق الصفحة الأساسية
`src/main.tsx`	ملف دخول التطبيق، مسؤول عن تركيب تطبيق React
`vite.config.ts`	ملف تكوين Vite، حيث يُكتب تكوين PWA الأساسي
`public/`	دليل الأصول الثابتة، حيث توضع أيقونات PWA ومواد SVG
`index.html`	ملف HTML للدخول، عادة لا يحتاج لتعديل

كمبتدئين، نهتم بشكل أساسي بثلاثة أجزاء:

App.tsx: يتحكم في سلوك البرنامج ويقرر "ما يظهر على الشاشة"
vite.config.ts: يكوّن سلوك PWA ويقرر "كيف يُثبت التطبيق ويُخزن مؤقتًا"
public/: يخزن أيقونات التطبيق والأصول

2.6 تحضير أيقونات التطبيق

PWA يحتاج إلى أيقونات قبل أن يمكن تثبيته. كحد أدنى، نحتاج إلى صورتين PNG بحجمي 192x192 و 512x512.

يمكنك طلب الذكاء الاصطناعي لتوليدهما:

text

Please help me generate two app icons with sizes 192x192 and 512x512.
Use a green gradient background and draw a red tomato in the middle. Save them in the public folder.

أو يمكنك أيضًا إنشاء أيقوناتك الخاصة بأي أداة تصميم (Figma، Canva) ووضعها في دليل public/.

2.7 تكوين `vite-plugin-pwa`

هذه هي الخطوة الأكثر أهمية. افتح vite.config.ts واطلب من الذكاء الاصطناعي تكوين إضافة PWA:

text

Please help me change vite.config.ts into a PWA configuration so the webpage can be installed to a phone home screen:
- The app name is "Tomato Farm", with a green theme
- Use icon-192.png and icon-512.png from the public directory as icons
- Enable automatic updates
- Cache all js, css, html, and image files so the app can work offline

سيُولد الذكاء الاصطناعي تكوينًا مشابهًا لهذا:

typescript

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

export default defineConfig({
  plugins: [
    react(),
    VitePWA({
      registerType: 'autoUpdate',
      manifest: {
        name: 'Tomato Farm',
        short_name: 'Tomato Farm',
        description: 'Focus, plant, and grow',
        theme_color: '#4CAF50',
        background_color: '#ffffff',
        display: 'standalone',
        icons: [
          {
            src: '/icon-192.png',
            sizes: '192x192',
            type: 'image/png'
          },
          {
            src: '/icon-512.png',
            sizes: '512x512',
            type: 'image/png'
          }
        ]
      },
      workbox: {
        globPatterns: ['**/*.{js,css,html,ico,png,svg}']
      }
    })
  ]
})

شرح التكوين الرئيسي:

registerType: 'autoUpdate': عند نشر نسخة جديدة، سيُحدّث التطبيق تلقائيًا في المرة التالية التي يفتحها المستخدمون، بدون تشغيل يدوي.
display: 'standalone': بعد التثبيت، يعمل في نافذته الخاصة، بدون شريط عنوان المتصفح، ويبدو كتطبيق أصلي.
workbox.globPatterns: يخبر Service Worker بأنواع الملفات التي يجب تخزينها مؤقتًا والوصول إليها بدون اتصال.

3 بناء Tomato Farm PWA

في الفصلين السابقين، فهمنا بالفعل ما هي PWA وأكملنا إعداد البيئة. من هذا القسم فصاعدًا، نتوقف عن التحدث نظريًا فقط وندخل في الممارسة العملية. سنستخدم وضع Vibe Coding لبناء تطبيق ممتع وعملي من الصفر - Tomato Farm. يجمع بشكل مثالي بين تقنية بومودورو والمحفزات المحولة إلى لعبة ويغطي العناصر الأساسية لتطوير PWA: تفاعل واجهة المستخدم (عداد بومودورو)، تخزين البيانات (النقاط والمحاصيل)، وقدرة العمل بدون اتصال (التخزين المؤقت عبر Service Worker).

الآن، دعنا نرسل التعليمات الأولى إلى الذكاء الاصطناعي.

3.1 أول "موجه رئيسي": من الصفر إلى الواحد

في وضع Vibe Coding، لا نحتاج لاتباع النهج التقليدي المتمثل في إنشاء ملفات التخطيط أولاً ثم كتابة كود المنطق. ما نحتاج إلى فعله هو وصف المتطلبات بوضوح في طلقة واحدة ودع الذكاء الاصطناعي يولد النسخة الأولى القابلة للتشغيل.

افتح دليل المشروع الذي أنشأناه للتو في مساعد البرمجة بالذكاء الاصطناعي، وأدخل الموجه التالي:

text

Please help me write the main page for the Tomato Farm app, with the following functions:

**Pomodoro Timer**
- A 25-minute countdown timer with start, pause, and reset
- Show remaining time and a progress bar
- Give the user 10 points after completing one focus session

**Farming System**
- 3 plots of farmland, but initially only the first one is available; the later ones are unlocked after leveling up
- A shop to buy seeds: carrot costs 5 points, tomato 10 points, corn 15 points
- After buying seeds and planting them, crops slowly grow, and when mature they can be harvested for points

**Level System**
- Level by total points: 0-100 points = Beginner Farmer, 100-300 = Skilled Farmer, above 300 = Farm Master
- Unlock new land and better seeds after leveling up

**UI Design**
- Top shows level, points, and upgrade progress bar
- Middle shows the Pomodoro countdown
- Below is the farmland grid
- Bottom has the shop button
- Use a green theme and make it look fresh and cute
- Must adapt to phone screens

**Data Saving**
- All data (points, level, farmland state) must be saved, and refreshing the page should not lose it

بعد الإرسال، سترى الذكاء الاصطناعي يبدأ في التفكير وتحليل هيكل مشروعك. بعد بضع ثوانٍ، سيولد مباشرة الكود الكامل لـ App.tsx.

من رده، يمكننا رؤية منطقه في التفكير والتفاعل
يمكننا رؤية مباشرة أي كود غيّره
إذا لم نكن راضين، يمكننا التراجع إلى النسخة السابقة

3.2 التشغيل والمعاينة (خادم التطوير المحلي)

الآن أكمل الذكاء الاصطناعي الجولة الأولى من التطوير، لكن تذكر: ما نراه في مساعد البرمجة لا يزال مجرد "مخططات" كود، وليس تطبيقًا تفاعليًا حقيقيًا. نحتاج إلى بدء خادم تطوير محلي حتى نتمكن فعلًا من تشغيل الكود ورؤية التأثير الحقيقي.

شغّل هذا في طرفية مساعد البرمجة بالذكاء الاصطناعي:

bash

npm run dev

بعد بضع ثوانٍ، ستُظهر الطرفية مخرجات مثل هذه:

text

  VITE v5.0.0  ready in 300 ms

  ->  Local:   http://localhost:5173/
  ->  Network: use --host to expose
  ->  press h + enter to show help

افتح http://localhost:5173/ في المتصفح، وينبغي أن ترى:

مستوى ونقاط وشريط تقدم في الأعلى
عداد بومودورو في المنتصف
منطقة الأراضي الزراعية أدناه
زر المتجر في الأسفل

جرب النقر على زر "ابدأ التركيز" وانظر إذا كان العداد يعمل بشكل صحيح. انقر على قطعة أرض زراعية وانظر إذا كان يمكنك شراء البذور وزرعها. هذه هي النسخة الأولى من تطبيق PWA الخاص بك.

3.3 تكرار التحسين (إضافة محاصيل SVG ورسوم متحركة)

في هذه المرحلة، تطبيقنا لديه بالفعل شكل أساسي: عداد بومودورو ونظام الزراعة ونظام المستويات. لكنه قد لا يزال يبدو خشنًا، مع محاصيل ربما تُعرض كنص فقط أو كتل بسيطة. بعد ذلك، سنضيف محاصيل SVG جميلة ورسوم نمو نمطية لجعل Tomato Farm ينبض بالحياة.

هذا بالضبط حيث يصبح Vibe Coding جذابًا جدًا. في التطوير التقليدي، رسم رسومات SVG وبناء رسوم نمو نمطية معقدة يمكن أن يكون كابوسًا للمبتدئين. لا تحتاج فقط للتعامل مع رسم مسارات SVG، بل أيضًا حساب منحنيات الرسوم المتحركة. في وضع Vibe Coding، لا تحتاج للقلق بشأن هذه التفاصيل المنخفضة المستوى. فقط أخبر الذكاء الاصطناعي كمخرج: "أعط المحاصيل رسومات SVG أجمل واجعلها تنمو مع رسوم متحركة"، والكود المعقد يظهر تقريبًا فورًا.

الخطوة 1: تحضير أصول محاصيل SVG

يمكنك طلب الذكاء الاصطناعي رسم SVG مباشرة في الكود، أو تحضير ملفات SVG ووضعها تحت public/. في هذا الدرس، نوصي بترك الذكاء الاصطناعي يولد كود SVG مباشرة لأنه أكثر مرونة.

الخطوة 2: إرسال تعليمات تكرارية

ارجع إلى مساعد البرمجة بالذكاء الاصطناعي وأدخل الموجه التالي:

text

Please make the crops look better and add growth animation:

**Crop graphics**
- Carrot: orange body with green leaves
- Tomato: red round shape with little green leaves
- Corn: yellow corn cob with green outer leaves
Just use simple shapes

**Growth animation**
- When first planted, it starts as a small sprout and gradually grows to maturity
- Show 3 stages

**Harvest effect**
- When clicking a mature crop, play a simple harvest animation
- Show how many points were gained

**Overall polish**
- Farmland tiles should have borders and background color
- Crops should appear centered in the tile
- Overall style should feel a little cuter

سيعدّل الذكاء الاصطناعي الكود مرة أخرى ويتعامل مع عرض SVG ومنطق الرسوم المتحركة. بعد الانتهاء، حدّث المتصفح، وينبغي أن ترى رسومات محاصيل أجمل ورسوم نمو سلسة.

3.4 إضافة مؤثرات صوتية وإشعارات (اختياري)

إذا كنت تريد أن يكون Tomato Farm أكثر غمرًا، يمكنك أيضًا إضافة مؤثرات صوتية وإشعارات. هذا يحتاج أيضًا فقط إلى موجه بسيط:

text

Please add sound effects and notifications to Tomato Farm:

**Sound effects**
- Play a "ding" when focus starts
- Play a victory sound when focus is completed
- Also add matching sound effects for planting and harvesting

**Notifications**
- Show "Congratulations, you finished a focus session!" after a focus cycle ends
- Show "Congratulations, you leveled up to XX!" when leveling up
- Show "You unlocked a new farmland plot!" when new land is unlocked

You can implement this with simple audio files or the Web Audio API

سيساعدك الذكاء الاصطناعي على إضافة مؤثرات صوتية وإشعارات، مما يجعل Tomato Farm أكثر حيوية ومتعة.

4 تجربة PWA محليًا

4.1 البناء والمعاينة

Service Worker لـ PWA يسري فقط في بنيات الإنتاج (لن يسجل في وضع التطوير). لذلك نحتاج للبناء أولاً ثم المعاينة:

text

Please help me run these commands:
1. npm run build (build production version)
2. npm run preview (start local preview server)

بعد البناء، سيُولد Vite جميع الملفات في دليل dist/، بما في ذلك sw.js (Service Worker) المُولد تلقائيًا و manifest.webmanifest.

بمجرد بدء خادم المعاينة، افتح العنوان الموضح في الطرفية (عادةً http://localhost:4173).

4.2 تثبيت PWA على سطح المكتب

بعد فتح عنوان URL المعاينة، ستلاحظ أن أيقونة تثبيت تظهر على الجانب الأيمن من شريط عنوان المتصفح (عادةً سهم تنزيل صغير أو علامة "+").

خطوات تثبيت Chrome / Edge:

انقر على أيقونة التثبيت على الجانب الأيمن من شريط العنوان
انقر Install في مربع الحوار المنبثق
سيفتح PWA في نافذة مستقلة، وسيُنشأ اختصار على سطح المكتب / قائمة ابدأ / Dock

يبدو PWA المثبت تمامًا مثل تطبيق سطح مكتب أصلي - بدون شريط عنوان، بدون علامات تبويب، بنافذته وأيقونته الخاصة. الآن يمكنك فتح Tomato Farm في أي وقت وبدء رحلة التركيز والزراعة.

خطوات تثبيت macOS Safari:

افتح عنوان URL لـ PWA في Safari
انقر File -> Add to Dock من شريط القائمة
ستظهر أيقونة PWA في Dock

4.3 اختبار قدرة العمل بدون اتصال

هذا هو أروع جزء في PWA. دعنا نتحقق مما إذا كان وضع العمل بدون اتصال يعمل فعلًا:

تأكد من فتح PWA في المتصفح مرة واحدة على الأقل (حتى يتمكن Service Worker من تخزين الموارد مؤقتًا)
اقطع الشبكة (أوقف Wi-Fi أو انزع الكابل)
حدّث الصفحة - ستجد أن Tomato Farm لا يزال يحمل بشكل طبيعي!
ابدأ جلسة بومودورو - بعد الانتهاء تكسب نقاطًا، تشتري بذورًا، تزرع محاصيل - وكل البيانات لا تزال تُحفظ بشكل طبيعي في localStorage

يمكنك أيضًا فتح Chrome DevTools (F12) -> Application -> Service Workers لفحص حالة Service Worker وقائمة الموارد المخزنة مؤقتًا.

4.4 استمرارية البيانات وخيارات المزامنة

الآن يمكن لـ Tomato Farm الخاص بك العمل بدون اتصال بالفعل، وجميع البيانات مخزنة في localStorage للمتصفح. لكن هناك مشكلة رئيسية واحدة: إذا بدّل المستخدم الأجهزة أو مسح بيانات المتصفح، ستضيع جميع بيانات المزرعة. للتطبيقات الإنتاجية الجادة، نحتاج للتفكير في استمرارية البيانات والمزامنة عبر الأجهزة.

4.4.1 قيود التخزين المحلي

localStorage الذي نستخدمه حاليًا لديه عدة قيود واضحة:

القيد	الوصف
مرتبط بالجهاز	البيانات مخزنة فقط في المتصفح الحالي على الجهاز الحالي؛ تبديل الأجهزة يعني فقدانها
سعة محدودة	عادةً فقط 5-10 ميغابايت من مساحة التخزين
سهلة الفقدان	مسح بيانات المتصفح أو إلغاء تثبيت PWA يسبب فقدان البيانات
لا يمكن المزامنة	التقدم على الهاتف لا يمكن مزامنته إلى سطح المكتب

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

4.4.2 الخيار 1: المزامنة السحابية (موصى به)

الحل الأكثر موثوقية هو مزامنة البيانات مع قاعدة بيانات سحابية. بالنسبة لـ PWA، Supabase هو خيار ممتاز - يوفر قاعدة بيانات PostgreSQL واشتراكات في الوقت الفعلي والمصادقة، ويقدم أيضًا مستوى مجاني.

فكرة التنفيذ:

تسجيل دخول المستخدم: استخدام البريد الإلكتروني أو تسجيل الدخول الاجتماعي لإنشاء هوية المستخدم
مزامنة بيانات تلقائية: كل عملية تُحفظ تلقائيًا في السحابة
الأولوية للعمل بدون اتصال: التطبيق لا يزال يعمل بدون اتصال، ثم يتزامن تلقائيًا عند عودة الشبكة
المزامنة عبر الأجهزة: التقدم على الهاتف متاح فورًا على سطح المكتب

مثال على الموجه:

text

Please help me migrate Tomato Farm data storage from localStorage to Supabase cloud sync:

**Functional requirements**
- Add user login (email + password or Google login)
- Save user data (points, level, farmland state) to Supabase database
- Still work offline, and automatically sync when the network recovers
- Support multi-device sync, so crops planted on the phone can also be seen on desktop

**Tech stack**
- Use @supabase/supabase-js client
- Implement optimistic updates (update UI first, then sync to cloud)
- Add a simple sync status indicator

المزايا:

البيانات لن تضيع؛ يحتاج المستخدمون فقط لتسجيل الدخول مرة أخرى عند تبديل الأجهزة
المستوى المجاني كافٍ للمشاريع الشخصية
يدعم الاشتراكات في الوقت الفعلي، مما يعطي تجربة مزامنة جيدة عبر الأجهزة

العيوب:

يتطلب تسجيل/تسجيل دخول المستخدم، مما يضيف احتكاكًا في الاستخدام
يحتاج اتصال شبكة لإجراء المزامنة

4.4.3 الخيار 2: النسخ الاحتياطي عبر التصدير / الاستيراد

إذا كنت لا تريد إضافة خدمة خلفية، فالحل الوسط الأبسط هو النسخ الاحتياطي والاستعادة اليدويين.

فكرة التنفيذ:

التصدير: حزم بيانات المزرعة كملف JSON ودع المستخدمين ينزلونه
الاستيراد: يمكن للمستخدمين اختيار ملف JSON مُصدّر مسبقًا لاستعادة البيانات
تذكير تلقائي: تذكير المستخدمين بالنسخ الاحتياطي بشكل دوري

مثال على الموجه:

text

Please add data backup functionality to Tomato Farm:

**Export**
- Add an "Export Data" button on the settings page
- Package all data in localStorage into a JSON file
- Automatically download it to the user's device

**Import**
- Add an "Import Data" button that accepts a JSON file
- Validate file format before restoring
- Show a warning before import because it overwrites current data

**Automatic reminders**
- If the user has not backed up for over 7 days, show a friendly reminder

المزايا:

بسيط في التنفيذ، لا حاجة لخدمة خلفية
المستخدمون يتحكمون بالكامل في بياناتهم
يمكن النقل عبر الأجهزة بمشاركة الملف المُصدّر

العيوب:

يتطلب تشغيلًا يدويًا، لذا التجربة ليست سلسة
إذا نسي المستخدم النسخ الاحتياطي، لا تزال البيانات يمكن أن تضيع

4.4.4 الخيار 3: مزامنة إضافة المتصفح (لمستخدمي Chrome)

إذا كان PWA يستهدف بشكل أساسي مستخدمي Chrome، يمكنك النظر في Chrome Storage Sync API. هذه خدمة تخزين متزامنة عبر الأجهزة يوفرها Chrome، حيث تتزامن البيانات تلقائيًا مع حساب Google الخاص بالمستخدم.

ملاحظة: هذا يتطلب تغليف PWA أيضًا كإضافة Chrome، وهو أكثر ملاءمة للمطورين ذوي الخبرة التقنية.

4.4.5 استراتيجية الاختيار الموصى بها

السيناريو	الحل الموصى به
أداة شخصية خفيفة	`localStorage` فقط كافٍ
تريد تجنب فقدان البيانات، لكن بدون تعقيد كبير	النسخ الاحتياطي عبر التصدير / الاستيراد
منتج رسمي بتجربة مستخدم أفضل	المزامنة السحابية Supabase
بشكل أساسي لمستخدمي Chrome	Chrome Storage Sync

لتطبيق مثل Tomato Farm، اقتراحي هو:

مرحلة MVP: ابدأ بـ localStorage للتحقق من فكرة المنتج بسرعة
مرحلة التكرار: أضف النسخ الاحتياطي عبر التصدير / الاستيراد حتى يكون لدى المستخدمين شبكة أمان للبيانات
مرحلة النضج: ادخل Supabase لتحقيق مزامنة سحابية حقيقية

تذكر: التحسين التدريجي هو الفلسفة الأساسية لـ PWA. اجعل التطبيق يعمل أولاً، ثم أضف تدريجيًا قدرات أكثر تقدمًا.

5 النشر عبر الإنترنت

PWA يجب أن يعمل تحت HTTPS ليعمل بشكل صحيح. الخبر الجيد هو أن منصات النشر الرئيسية توفر الآن HTTPS مجاني تلقائيًا. سنستخدم Vercel كمثال (يمكنك أيضًا استخدام Netlify أو GitHub Pages).

5.1 النشر على Vercel

الخطوة 1: تثبيت أداة النشر

text

Please help me install Vercel's deployment tool

الخطوة 2: نشر المشروع

text

Please help me deploy this project to Vercel. The project name is tomato-farm-pwa

سيتعامل الذكاء الاصطناعي مع خطوات النشر تلقائيًا. تحتاج فقط إلى:

اختيار حسابك
تأكيد إنشاء مشروع جديد
الاحتفاظ بالخيارات الأخرى على الوضع الافتراضي

بعد الانتظار بضع عشرات من الثواني، سيبني Vercel وينشر مشروعك تلقائيًا. عند الانتهاء، ستحصل على عنوان URL بـ HTTPS مثل https://tomato-farm-pwa.vercel.app.

الخطوة 3: التحقق من PWA

افتح عنوان URL المنشور في المتصفح، وينبغي أن ترى:

أيقونة تثبيت تظهر على الجانب الأيمن من شريط العنوان
في DevTools -> Application -> Manifest، معلومات التطبيق التي كوّنتها مثل الاسم "Tomato Farm"
في علامة تبويب Service Workers، Service Worker معروض كمفعّل

5.2 النشر عبر GitHub Pages (بديل)

إذا كنت تفضل GitHub Pages، تحتاج إلى تكوين مسار إضافي:

text

Please help me modify the config so the project can be deployed to GitHub Pages.
My repository name is tomato-farm-pwa, so please adjust the path configuration accordingly.

ثم ادفع مخرجات البناء إلى فرع gh-pages في مستودع GitHub الخاص بك.

6 تثبيت PWA على الهاتف

هذا هو الجزء الأكثر إثارة - تحويل صفحة Tomato Farm الخاصة بك إلى "تطبيق" على هاتفك.

6.1 التثبيت على Android

افتح عنوان URL لـ Tomato Farm PWA المنشور في متصفح Chrome على هاتفك
قد يُظهر Chrome تلقائيًا شعار "Add to Home screen" - فقط انقر عليه
إذا لم يظهر تلقائيًا، اضغط على قائمة النقاط الثلاث في أعلى اليمين -> Install app أو Add to Home screen
أكد التثبيت، وستظهر أيقونة تطبيق Tomato Farm على الشاشة الرئيسية لهاتفك

افتحه ستلاحظ أنه يعمل في وضع ملء الشاشة، بدون شريط عنوان المتصفح أو أزرار التنقل، ويبدو تقريبًا مثل تطبيق أصلي. الآن يمكنك بدء التركيز والزراعة في أي وقت.

6.2 التثبيت على iPhone

على iOS، يمكن تثبيت PWA فقط من خلال متصفح Safari (المتصفحات الأخرى لا تدعم التثبيت):

افتح عنوان URL لـ Tomato Farm PWA المنشور في Safari
اضغط على زر Share في الأسفل (مربع به سهم لأعلى)
في القائمة، اختر Add to Home Screen
أعطِ التطبيق اسمًا واضغط Add

بدءًا من iOS 26، ستفتح جميع المواقع المضافة إلى الشاشة الرئيسية في وضع التطبيق المستقل افتراضيًا، وهو تحسين كبير.

قيود معروفة على iOS:
الإشعارات الفورية تتطلب iOS 16.4 أو أحدث، ويجب أن يكون PWA مضافًا بالفعل إلى الشاشة الرئيسية
Background Sync غير مدعوم
مساحة التخزين أكثر محدودية من Android

6.3 تدقيق PWA الخاص بك باستخدام Lighthouse

توفر Google أداة تُسمى Lighthouse يمكنها تقييم PWA الخاص بك. افتح Chrome DevTools (F12) -> Lighthouse -> حدد "Progressive Web App" -> انقر "Analyze page load."

ينبغي أن يحصل Tomato Farm PWA المؤهل على درجة كاملة في فئة PWA. إذا لم يكن كذلك، سيخبرك Lighthouse بالأسباب الدقيقة ويقترح إصلاحات.

7 الخلاصة

تهانينا! لقد بنيت بنجاح PWA بومودورو زراعي يمكن تثبيته على كل من سطح المكتب والهاتف. دعنا نراجع ما فعلناه:

أنشأنا تطبيق Tomato Farm ويب باستخدام Vite + React
أضفنا Service Worker وManifest عبر vite-plugin-pwa
نشرناه على Vercel للحصول على عنوان URL بـ HTTPS
ثبّتناه بنجاح على كل من سطح المكتب والهاتف واختبرنا قدرة العمل بدون اتصال

الآن يمكن لـ Tomato Farm PWA الخاص بك فعلًا تحقيق:

الزراعة المركزة: مساعدة المستخدمين على البقاء مركزين من خلال آلية بومودورو
المكافآت المحولة إلى لعبة: استخدام الزراعة والمستويات والفتح لتحفيز الاستخدام المتكرر
الاستخدام بدون اتصال: حتى بدون شبكة، يمكن للمستخدمين التركيز والزراعة وإدارة مزرعتهم
التثبيت المشترك بين المنصات: طوّر مرة واحدة وثبّت على أنواع متعددة من الأجهزة

سحر PWA في "تدرجه" - لا تحتاج لجعله مثاليًا من البداية. اجعل الموقع قابلاً للتثبيت ومتاحًا بدون اتصال أولاً، ثم أضف تدريجيًا قدرات متقدمة مثل الإشعارات الفورية والمزامنة في الخلفية.

اتجاهات متقدمة:

الإشعارات الفورية: استخدام Push API + Notification API لتذكير المستخدمين عند انتهاء بومودورو أو عندما تكون المحاصيل جاهزة للحصاد
المزامنة في الخلفية: استخدام Background Sync API لمزامنة بيانات المزرعة إلى السحابة بعد عودة الشبكة
استراتيجيات تخزين مؤقت أذكى: استخدام استراتيجيات Workbox مختلفة مثل CacheFirst وNetworkFirst وStaleWhileRevalidate لأنواع مختلفة من الأصول
النشر على متاجر التطبيقات: استخدام PWA Builder لتغليف Tomato Farm PWA في APK لنظام Android أو تطبيق Microsoft Store
الميزات الاجتماعية: إضافة نظام أصدقاء حتى يتمكن المستخدمون من زيارة مزارع بعضهم البعض وتبادل المحاصيل

قاعدة كود واحدة، جميع المنصات - هذه هي قوة PWA. ركز، ازرع، وانمو!

كيف تبني تطبيق PWA محلي: تحويل موقع ويب إلى "تطبيق حقيقي" ​

1 ما هي PWA وما هو تطوير PWA ​

1.1 تعريف PWA ​

لماذا لا يمكن للمواقع العادية العمل بدون اتصال، لكن PWA يمكنها ذلك ​

PWA مقابل الموقع العادي مقابل التطبيق الأصلي ​

1.2 لماذا تختار PWA؟ ​

1.5 خريطة طريق الدرس ​

2 إعداد بيئة التطوير ​

2.1 الأدوات المستخدمة في هذا الدرس ​

2.2 تثبيت Node.js ​

2.3 تثبيت مساعد البرمجة بالذكاء الاصطناعي ​

2.4 إنشاء مشروع جديد ​

2.5 فهم هيكل المشروع ​

2.6 تحضير أيقونات التطبيق ​

2.7 تكوين vite-plugin-pwa ​

3 بناء Tomato Farm PWA ​

3.1 أول "موجه رئيسي": من الصفر إلى الواحد ​

3.2 التشغيل والمعاينة (خادم التطوير المحلي) ​

3.3 تكرار التحسين (إضافة محاصيل SVG ورسوم متحركة) ​

3.4 إضافة مؤثرات صوتية وإشعارات (اختياري) ​

4 تجربة PWA محليًا ​

4.1 البناء والمعاينة ​

4.2 تثبيت PWA على سطح المكتب ​

4.3 اختبار قدرة العمل بدون اتصال ​

4.4 استمرارية البيانات وخيارات المزامنة ​

4.4.1 قيود التخزين المحلي ​

4.4.2 الخيار 1: المزامنة السحابية (موصى به) ​

4.4.3 الخيار 2: النسخ الاحتياطي عبر التصدير / الاستيراد ​

4.4.4 الخيار 3: مزامنة إضافة المتصفح (لمستخدمي Chrome) ​

4.4.5 استراتيجية الاختيار الموصى بها ​

5 النشر عبر الإنترنت ​

5.1 النشر على Vercel ​

5.2 النشر عبر GitHub Pages (بديل) ​

6 تثبيت PWA على الهاتف ​

6.1 التثبيت على Android ​

6.2 التثبيت على iPhone ​

6.3 تدقيق PWA الخاص بك باستخدام Lighthouse ​

7 الخلاصة ​

المراجع ​

كيف تبني تطبيق PWA محلي: تحويل موقع ويب إلى "تطبيق حقيقي"

1 ما هي PWA وما هو تطوير PWA

1.1 تعريف PWA

لماذا لا يمكن للمواقع العادية العمل بدون اتصال، لكن PWA يمكنها ذلك

PWA مقابل الموقع العادي مقابل التطبيق الأصلي

1.2 لماذا تختار PWA؟

1.5 خريطة طريق الدرس

2 إعداد بيئة التطوير

2.1 الأدوات المستخدمة في هذا الدرس

2.2 تثبيت Node.js

2.3 تثبيت مساعد البرمجة بالذكاء الاصطناعي

2.4 إنشاء مشروع جديد

2.5 فهم هيكل المشروع

2.6 تحضير أيقونات التطبيق

2.7 تكوين `vite-plugin-pwa`

3 بناء Tomato Farm PWA

3.1 أول "موجه رئيسي": من الصفر إلى الواحد

3.2 التشغيل والمعاينة (خادم التطوير المحلي)

3.3 تكرار التحسين (إضافة محاصيل SVG ورسوم متحركة)

3.4 إضافة مؤثرات صوتية وإشعارات (اختياري)

4 تجربة PWA محليًا

4.1 البناء والمعاينة

4.2 تثبيت PWA على سطح المكتب

4.3 اختبار قدرة العمل بدون اتصال

4.4 استمرارية البيانات وخيارات المزامنة

4.4.1 قيود التخزين المحلي

4.4.2 الخيار 1: المزامنة السحابية (موصى به)

4.4.3 الخيار 2: النسخ الاحتياطي عبر التصدير / الاستيراد

4.4.4 الخيار 3: مزامنة إضافة المتصفح (لمستخدمي Chrome)

4.4.5 استراتيجية الاختيار الموصى بها

5 النشر عبر الإنترنت

5.1 النشر على Vercel

5.2 النشر عبر GitHub Pages (بديل)

6 تثبيت PWA على الهاتف

6.1 التثبيت على Android

6.2 التثبيت على iPhone

6.3 تدقيق PWA الخاص بك باستخدام Lighthouse

7 الخلاصة

المراجع