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

استخدام حِزَم npm

يمكنك تثبيت واستخدام أي حزمة npm في تطبيقك. يتم تجميع كلٍ من الدوال المنطقية والمكوّنات الأمامية باستخدام esbuild، والذي يُضمّن جميع التبعيات ضمن المخرجات — لا حاجة إلى node_modules وقت التشغيل.

تثبيت حزمة

ثم استوردها في شيفرتك:
src/logic-functions/fetch-data.ts
وينطبق الأمر نفسه على المكوّنات الأمامية:
src/front-components/chart.tsx

كيف يعمل التجميع

تستخدم خطوة البناء أداة esbuild لإنتاج ملف واحد مستقل لكل دالة منطقية ولكل مكوّن أمامي. تُضمَّن جميع الحزم المستوردة داخل الحزمة. الدوال المنطقية تعمل في بيئة Node.js. الوحدات المدمجة في Node (fs وpath وcrypto وhttp وغيرها) متاحة ولا تحتاج إلى تثبيت. المكوّنات الأمامية تعمل ضمن Web Worker. وحدات Node المدمجة غير متاحة — المتاح فقط واجهات برمجة المتصفّح وحِزَم npm التي تعمل في بيئة المتصفّح. كلتا البيئتين تحتويان على twenty-client-sdk/core وtwenty-client-sdk/metadata كوحدات متاحة مُسبقًا — لا تُضمَّن هذه ضمن الحزم بل تُحلّ وقت التشغيل بواسطة الخادم.

إعداد

يتضمّن التطبيق المُولَّد بالقالب بالفعل Vitest. إذا أعددته يدويًا، فثبّت التبعيات:
أنشئ vitest.config.ts في جذر تطبيقك:
vitest.config.ts
أنشئ ملف إعداد عام يتحقق من إمكانية الوصول إلى الخادم، ويكتب ملف إعداد اختبار لـ SDK (~/.twenty/config.test.json)، ويزامن التطبيق قبل تشغيل الاختبارات:
src/__tests__/global-setup.ts

واجهات SDK البرمجية

يُصدِّر المسار الفرعي twenty-sdk/cli دوالًا يمكنك استدعاؤها مباشرةً من شيفرة الاختبار: تُرجع كل دالة كائن نتيجة يحتوي على success: boolean وعلى إمّا data أو error.

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

إليك مثالًا كاملًا يبني التطبيق وينشره ويثبّته، ثم يتحقّق من ظهوره في مساحة العمل:
src/__tests__/app-install.integration-test.ts

تشغيل الاختبارات

تأكّد من تشغيل خادم Twenty المحلي لديك، ثم:
أو في وضع المراقبة أثناء التطوير:

التحقق من الأنواع

يمكنك أيضًا تشغيل التحقق من الأنواع على تطبيقك دون تشغيل الاختبارات:
يشغِّل هذا الأمر tsc --noEmit على ملف tsconfig.json الخاص بتطبيقك ويبلغ عن أي أخطاء في الأنواع. كما تتضمن التطبيقات المُنشأة بالهيكل برنامج نصي yarn typecheck يشمل ملفات الاختبار (tsconfig.spec.json) أيضًا.

التكامل المستمر (CI) باستخدام GitHub Actions

تولّد أداة إنشاء الهيكل سير عمل جاهزًا للاستخدام في .github/workflows/ci.yml. عند كل دفع إلى الفرع main وكل طلب سحب، تُنشئ الأداة خادم Twenty مؤقتًا في بيئة التشغيل (عبر الإجراء twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test)، ثم تشغِّل الأوامر yarn lint وyarn typecheck وyarn test:unit وyarn test مع ضبط المتغيرين TWENTY_API_URL وTWENTY_API_KEY للإشارة إلى ذلك الخادم. لا تُطلَب أي أسرار، ويمكنك تثبيت إصدار الخادم عبر متغير البيئة TWENTY_VERSION في أعلى سير العمل. راجع قسم النشر → التكامل/التسليم المستمران الآليان للاطلاع على شرح كامل لثلاثة مسارات العمل التي تم إنشاؤها تلقائياً (ci.yml، وخط أنابيب النشر cd.yml، وpublish.yml للنشر على npm).