---
title: البدء السريع
icon: rocket
description: أنشئ أول تطبيق Twenty خلال دقائق.
---

## المتطلبات الأساسية

* **Node.js 24+** — [تنزيل](https://nodejs.org/)
* **Yarn 4** — يأتي مع Node.js عبر Corepack. قم بتمكينه: `corepack enable`
* **Docker** — [تنزيل](https://www.docker.com/products/docker-desktop/). مطلوب لتشغيل خادم Twenty محليًا. تخطَّ ذلك إذا كان لديك Twenty يعمل في مكان آخر.

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

| المرحلة             | ماذا تفعل                          | الأداة                        | النتيجة                         |
| ------------------- | ---------------------------------- | ----------------------------- | ------------------------------- |
| **1. تهيئة الهيكل** | توليد الشفرة المصدرية للتطبيق      | `npx create-twenty-app`       | مشروع TypeScript على القرص      |
| **2. تشغيل خادم**   | بدء تشغيل خادم Twenty للمزامنة معه | Docker + `yarn twenty server` | مثيل Twenty قيد التشغيل         |
| **3. مزامنة**       | قم بمزامنة شفرتك مباشرةً مع الخادم | `yarn twenty dev`             | تظهر تغييراتك في واجهة المستخدم |

---

## المرحلة 1 — تهيئة هيكل مشروعك

أنشئ تطبيقًا جديدًا من القالب:

```bash filename="Terminal"
npx create-twenty-app@latest my-twenty-app
```

ستتم مطالبتك باسم ووصف — اضغط **Enter** للقيم الافتراضية. يُنشئ هذا مشروع TypeScript في `my-twenty-app/` يتضمن ملف بداية `application-config.ts`، ودورًا افتراضيًا، وسير عمل CI، واختبار تكامل.

**بعد هذه المرحلة:** سيكون لديك الشفرة المصدرية لتطبيق على جهازك. ليس قيد التشغيل بعد — وهذه هي المرحلة 2.

---

## المرحلة 2 — تشغيل خادم Twenty محلي

يحتاج تطبيقك إلى خادم Twenty للمزامنة معه. الخادم هو مثيل Twenty كامل — واجهة مستخدم، واجهة برمجة تطبيقات GraphQL، PostgreSQL — يعمل محليًا داخل Docker. ترفع شفرتك المحلية تعريفاتها إلى ذلك الخادم، مما يجعلها تظهر في واجهة المستخدم.

تقترح أداة توليد الهيكل تشغيل خادم لك:

> **هل ترغب في إعداد مثيل محلي من Twenty؟**

* **نعم (موصى به)** — ستسحب صورة Docker `twentycrm/twenty-app-dev` وتبدأ تشغيلها على المنفذ `2020`. تأكّد أولًا من أن Docker قيد التشغيل.
* **لا** — اختر هذا إذا كان لديك بالفعل خادم Twenty تريد الاتصال به. يمكنك ربطه لاحقًا باستخدام `yarn twenty remote:add`.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/start-instance.png" alt="هل يجب بدء المثيل المحلي؟" />
</div>

بمجرد أن يصبح الخادم جاهزًا، سيفتح المتصفح لإجراء تسجيل الدخول. استخدم حساب العرض التوضيحي المُجهَّز مسبقًا:

* **البريد الإلكتروني:** `tim@apple.dev`
* **كلمة المرور:** `tim@apple.dev`

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/login.png" alt="شاشة تسجيل الدخول إلى Twenty" />
</div>

انقر **Authorize** في الشاشة التالية — يمنح هذا واجهة سطر الأوامر CLI حق الوصول إلى مساحة العمل الخاصة بك.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/authorize.png" alt="شاشة تفويض واجهة الأوامر (CLI) الخاصة بـ Twenty" />
</div>

ستؤكّد الطرفية أن كل شيء قد تم إعداده.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="تم إنشاء هيكل التطبيق بنجاح" />
</div>

**بعد هذه المرحلة:** لديك خادم Twenty قيد التشغيل على [http://localhost:2020](http://localhost:2020)، مع تفويض CLI لديك للمزامنة معه.

<Note>
إذا لم يكن Docker مثبتًا أو قيد التشغيل، فستخبرك أداة توليد الهيكل بأمر البدء المناسب لنظام التشغيل لديك. عند تشغيل Docker، يمكنك المتابعة باستخدام `yarn twenty docker:start` — لا حاجة لإعادة إنشاء الهيكل.
</Note>

---

## المرحلة 3 — مزامنة تغييراتك

هذه هي الحلقة الداخلية التي ستقضي معظم وقتك فيها.

```bash filename="Terminal"
cd my-twenty-app
yarn twenty dev
```

يراقب هذا المجلد `src/`، ويُعيد البناء عند كل تغيير، ويزامن الناتج إلى الخادم. حرّر ملفًا، واحفظه، وخلال بضع ثوانٍ سينعكس التغيير على الخادم. سترى لوحة حالة مباشرة في الطرفية.

للحصول على مخرجات أكثر تفصيلاً (سجلات البناء، طلبات المزامنة، تتبعات الأخطاء)، أضِف `--verbose`.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/dev.png" alt="مخرجات الطرفية في وضع التطوير" />
</div>

افتح [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). يفترض أن ترى تطبيقك ضمن **Your Apps**.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="قائمة &#x22;Your Apps&#x22; تعرض &#x22;My twenty app&#x22;" />
</div>

انقر **My twenty app** لعرض **تسجيل التطبيق** — وهو سجل على مستوى الخادم يصف تطبيقك (الاسم، المعرّف، بيانات اعتماد OAuth، المصدر). يمكن تثبيت تسجيل واحد عبر عدة مساحات عمل على الخادم نفسه.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="تفاصيل تسجيل التطبيق" />
</div>

انقر **View installed app** لعرض التثبيت في مساحة العمل. تعرض علامة التبويب **About** الإصدار وخيارات الإدارة.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="التطبيق المثبت" />
</div>

**بعد هذه المرحلة:** لديك دورة تطوير حيّة. حرّر أي ملف في `src/` وسيظهر في واجهة المستخدم.

### مزامنة لمرة واحدة لـ CI والبرامج النصية

مرّر `--once` لتشغيل عملية بناء واحدة + مزامنة واحدة ثم الخروج — نفس خط الأنابيب، من دون مراقِب:

```bash filename="Terminal"
yarn twenty dev --once
```

| أمر                                | السلوك                                                              | متى يُستخدم                                                                 |
| ---------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| `yarn twenty dev`                  | يراقب ويعيد المزامنة عند كل تغيير. يستمر في العمل حتى توقفه.        | تطوير محلي تفاعلي.                                                          |
| `yarn twenty dev --once`           | بناء واحد + مزامنة واحدة، يخرج برمز `0` عند النجاح، و`1` عند الفشل. | CI، وخطافات ما قبل الالتزام، ووكلاء الذكاء الاصطناعي، وسير عمل مكتوب بنصوص. |
| `yarn twenty dev --once --dry-run` | يبني تغييرات البيانات الوصفية ويطبعها **من دون تطبيقها**.           | فحص ما الذي سيُغيِّره التزامن قبل تطبيقه.                                   |

كلا الوضعين يحتاجان إلى جهة بعيدة موثَّقة. راجع قسم [المزامنة والاستعادة](/l/ar/developers/extend/apps/operations/sync-and-recovery#previewing-changes-dry-run) للحصول على المزيد من المعلومات حول `--dry-run`.

### خيارات وضع التطوير

| خيار                                  | الوصف                                                                                 |
| ------------------------------------- | ------------------------------------------------------------------------------------- |
| `--once`                              | قم بالإنشاء والمزامنة مرة واحدة، ثم اخرج.                                             |
| `--dry-run`                           | باستخدام `--once`، يمكنك معاينة تغييرات البيانات الوصفية دون تطبيقها. لا يكتب أي شيء. |
| `--debounceMs \<ms>` | اضبط مهلة إزالة الارتداد لتغييرات الملفات بالميلي ثانية (القيمة الافتراضية: `2000`).  |
| `--verbose` / `--debug`               | إظهار سجلات إنشاء تفصيلية، وطلبات المزامنة، وتتبع الأخطاء.                            |

## ما الذي يمكنك بناؤه

تتكون التطبيقات من **كيانات** — يُعرَّف كل منها كملف TypeScript يحتوي على `export default` واحد:

| كيان                   | ماذا يفعل                                                                                     |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| **الكائنات والحقول**   | نماذج بيانات مخصّصة (بطاقة بريدية، فاتورة، إلخ) بحقول ذات أنواع محددة                         |
| **الوظائف المنطقية**   | TypeScript على جانب الخادم يتم تشغيله عبر مسارات HTTP، أو جداول cron، أو أحداث قاعدة البيانات |
| **المكوّنات الأمامية** | مكوّنات React تُعرَض داخل واجهة مستخدم Twenty (اللوحة الجانبية، الودجات، قائمة الأوامر)       |
| **المهارات والوكلاء**  | قدرات الذكاء الاصطناعي — تعليمات قابلة لإعادة الاستخدام ومساعدون مستقلون ذاتيًا               |
| **طرق العرض والتنقّل** | طرق عرض قوائم مُعدّة مسبقًا وعناصر قائمة الشريط الجانبي                                       |
| **تخطيطات الصفحات**    | صفحات تفاصيل سجلات مخصصة تتضمن علامات تبويب وعناصر واجهة                                      |

مرجع كامل: [المفاهيم](/l/ar/developers/extend/apps/getting-started/concepts).

## الخطوات التالية

<CardGroup cols={2}>
  <Card title="التهيئة" icon="screwdriver-wrench" href="/l/ar/developers/extend/apps/config/overview">
    هوية التطبيق، الدور الافتراضي، وخطّافات التثبيت، والأصول العامة.
  </Card>
  <Card title="بيانات" icon="database" href="/l/ar/developers/extend/apps/data/overview">
    الكائنات، الحقول، والعلاقات ثنائية الاتجاه.
  </Card>
  <Card title="المنطق" icon="bolt" href="/l/ar/developers/extend/apps/logic/overview">
    الوظائف المنطقية، المهارات، الوكلاء، واتصالات OAuth.
  </Card>
  <Card title="التخطيط" icon="table-columns" href="/l/ar/developers/extend/apps/layout/overview">
    العروض، التنقل، تخطيطات الصفحات، ومكوّنات الواجهة الأمامية.
  </Card>
  <Card title="العمليات" icon="rocket" href="/l/ar/developers/extend/apps/operations/overview">
    سطر الأوامر (CLI)، الاختبار، الوجهات البعيدة، التكامل المستمر (CI)، ونشر تطبيقك.
  </Card>
</CardGroup>
