إعداد React مع Electron

يبدأ إعداد React مع Electron بإنشاء مشروع Vite React، ثم إضافة electron وelectron-builder إلى devDependencies. وينتهي المشروع بنقطتي دخول: تطبيق Vite لعملية العرض وملف main.js للعملية الرئيسية في Electron.

يُعد main.js نقطة دخول Electron. فهو ينشئ BrowserWindow بأبعاد النافذة وإعدادات الأمان المطلوبة، ثم يحمّل تطبيق React؛ إذ يوجّهه إلى localhost:5173 أثناء التطوير وإلى مسار ملف مبني في بيئة الإنتاج.

electron-vite هي أداة بناء متكاملة تدمج Vite مع Electron، وتتولى تلقائيًا إعداد البناء المعقد متعدد العمليات. كما توفر إعدادات Vite منفصلة لـ main وpreload وrenderer، وتبسّط عمليات البناء أثناء التطوير والإنتاج بدرجة كبيرة.

عند ضبط Vite لـ Electron، يجب تحديد أهداف المتصفح صراحةً بدلًا من الاعتماد على الاكتشاف التلقائي، لأن عملية العرض تعمل على إصدار محدد من Chromium المضمّن في Electron. يتولى electron-vite ذلك تلقائيًا، لكن عمليات الإعداد اليدوي تتطلب تحديد إصدار chrome في هدف البناء.

يؤدي تشغيل electron-vite dev إلى بدء خادم التطوير في Vite لعملية العرض والعملية الرئيسية في Electron في الوقت نفسه. ويوفر خادم تطوير Vite ميزة الاستبدال السريع للوحدات، بحيث تظهر التغييرات التي تجريها على مكوّنات React فورًا في نافذة Electron من دون إعادة تشغيل كاملة.

يعمل HMR في عملية العرض في Electron كما يعمل في المتصفح؛ إذ يُعاد عرض المكوّنات المعدّلة فورًا مع الحفاظ على الحالة. ولا تتطلب إعادة تشغيل Electron كاملةً إلا التغييرات التي تطرأ على main.js أو سكريبت preload، لأنهما يعملان خارج نطاق HMR في Vite.

تحتاج مشاريع Electron + React + TypeScript إلى ملفات tsconfig منفصلة للعملية الرئيسية (التي تستهدف Node.js/CommonJS)، وpreload (التي تستهدف بيئة شبيهة بالمتصفح مع Node globals)، وعملية العرض (TypeScript القياسي للمتصفح). ينشئ electron-vite هذه الإعدادات تلقائيًا.

يستخدم سكريبت preload الدالة contextBridge.exposeInMainWorld لإتاحة واجهة برمجة التطبيقات المخصصة لعملية العرض. ويتمثل النمط المعتاد في إتاحة مساحة أسماء مثل "api"، تتضمن دوال تغلّف استدعاءات ipcRenderer.invoke، مما يمنح مكوّنات React واجهة غير متزامنة واضحة لعمليات العملية الرئيسية.

من أي مكوّن React، تستدعي window.api.myFunction() لاستدعاء واجهة preload المُتاحة. ويضيف مستخدمو TypeScript عادةً تصريحًا عامًا (window: Window & { api: MyAPI }) لكي يحصلوا على فحص الأنواع والإكمال التلقائي للواجهة المُتاحة.

يترجم electron-vite build الأهداف الثلاثة (main وpreload وrenderer) إلى مجلد dist/. ثم يحزّم electron-builder الناتج في مُثبّت خاص بالمنصة. ويحمّل main.js في بيئة الإنتاج عملية العرض من مسار الملف المضمّن بدلًا من عنوان URL لخادم التطوير.

أكثر أخطاء الإعداد شيوعًا هي: نسيان nodeIntegration:false وcontextIsolation:true (مما ينشئ ثغرات أمنية)، وتحميل عنوان URL غير صحيح في main.js (التطوير بدلًا من الإنتاج أو العكس)، واستيراد وحدات Electron مباشرةً في عملية العرض (مما يسبب أعطالًا). تمنع الإعدادات الافتراضية في electron-vite معظم هذه المشكلات.

ما الذي يحققه تشغيل electron-vite dev؟

يُبسَّط إعداد React مع Electron بفضل electron-vite، الذي يتولى تعقيدات البناء متعدد العمليات. ويوفر سير عمل التطوير دعمًا كاملًا لـ HMR، بينما يؤمّن contextBridge سطح واجهة برمجة التطبيقات لعملية العرض، وتضمن إعدادات TypeScript المنفصلة امتلاك كل عملية لبيئة الأنواع الصحيحة. وتستخدم عمليات بناء الإنتاج electron-builder لإنشاء حزم خاصة بالمنصة.