Skip to content

The open alternative to Salesforce, designed for AI.

11.0 KB
Raw Blame
---
title: هيكل المشروع
description: ما الذي يوجد داخل تطبيق Twenty المُهيكل مسبقًا — الملفات والمجلدات، وما الذي يفعله كلٌّ منها.
---

import { PageBanner } from "/snippets/page-banner.mdx"

## نظرة عامة

يبدو التطبيق الجديد الذي يتم إنشاؤه بواسطة `twenty app init` كما يلي:

```text filename="my-twenty-app/"
my-twenty-app/
  package.json
  yarn.lock                                 # Created by app init; used by yarn install
  src/
    application-config.ts                   # Required — your app's entry point
    default-role.ts                         # Permissions for logic functions
    constants/
      universal-identifiers.ts              # Auto-generated UUIDs and metadata
    front-components/
      main-page.tsx                         # Welcome page component
    logic-functions/
      health-check.ts                       # Reports whether the app can run
    navigation-menu-items/
      main-page.navigation-menu-item.ts     # Sidebar entry for the welcome page
    page-layouts/
      main-page.page-layout.ts              # Standalone page hosting the component
    __tests__/
      application-config.test.ts            # Unit test
      global-setup.ts                       # Integration test setup (sync + uninstall)
      run-twenty.ts                         # CLI subprocess helper for tests
      schema.integration-test.ts            # Integration test against a live server
  .github/workflows/
    ci.yml                                  # Lint, typecheck, unit + integration tests
    cd.yml                                  # Deploy + install on push to main
    publish.yml                             # Publish to npm on version tags (with provenance)
  public/
    logo.svg                                # Static assets
  locales/
    en.json                                 # Source catalog; add <locale>.json files next to it
  vitest.config.ts                          # Integration test runner config
  vitest.unit.config.ts                     # Unit test runner config
  tsconfig.json, tsconfig.spec.json
  .nvmrc, .yarnrc.yml, .oxlintrc.json
  README.md, AGENTS.md, CLAUDE.md, CHANGELOG.md, SETUP.md
```

## الملفات الرئيسية

| ملف / مجلد                                                                 | الغرض                                                                                                                                                                                                                                                                                                                                                      |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src/application-config.ts`                                                | **مطلوب.** ملف الإعداد الرئيسي لتطبيقك.                                                                                                                                                                                                                                                                                                                    |
| `src/default-role.ts`                                                      | دور افتراضي يتحكّم بما يمكن لدوال المنطق الوصول إليه.                                                                                                                                                                                                                                                                                                      |
| `src/constants/universal-identifiers.ts`                                   | معرّفات UUID وبيانات تعريف يتم توليدها تلقائيًا (اسم العرض، الوصف).                                                                                                                                                                                                                                                                                        |
| `src/front-components/`, `src/navigation-menu-items/`, `src/page-layouts/` | صفحة ترحيب مبدئية: مكوّن واجهة أمامية يتم تقديمه بواسطة مخطط صفحة مستقل، يمكن الوصول إليه من الشريط الجانبي.                                                                                                                                                                                                                                               |
| `src/logic-functions/health-check.ts`                                      | [فحص صحة](/ar/developers/extend/apps/logic/logic-functions#health-check) مبدئي يُبلغ عن `ok`. املأه لإظهار مشكلات التهيئة التي لا يمكن اكتشافها إلا بواسطة تطبيقك.                                                                                                                                                                                            |
| `src/__tests__/`                                                           | اختبار وحدة بالإضافة إلى اختبار تكامل (مع إعداده العام) يقوم بمزامنة التطبيق مع خادم حقيقي.                                                                                                                                                                                                                                                                |
| `public/`                                                                  | أصول ثابتة (صور، خطوط) تُقدَّم مع تطبيقك.                                                                                                                                                                                                                                                                                                                  |
| `locales/`                                                                 | كتالوجات الترجمة. يُعدّ `en.json` كتالوج المصدر الذي يملؤه `twenty app translations extract`؛ ومجموعة الملفات هنا هي ما تنشره المزامنة، لذا فإن المجلد الفارغ لا يعلن عن أي ترجمات. تتم كتابة `locales/compiled/` بواسطة `twenty app pull` للإدخالات التي لا تكون سلاسل مصدرها موجودة في الشجرة بعد، كما تنشره المزامنة أيضاً، وليس مخصصاً للتحرير اليدوي. |
| `AGENTS.md` / `CLAUDE.md`                                                  | إرشادات لوكلاء برمجة الذكاء الاصطناعي الذين يعملون على التطبيق.                                                                                                                                                                                                                                                                                            |
| `CHANGELOG.md` / `SETUP.md`                                                | سجل بأبرز التغييرات وتعليمات الإعداد للتطوير المحلي.                                                                                                                                                                                                                                                                                                       |

<Note>
  **تنظيم الملفات متروك لك.** المجلدات أعلاه هي اصطلاحات — تكتشف
  واجهة سطر الأوامر الكيانات عبر تحليل AST لاستدعاءات `export default defineEntity(...)`
  بغض النظر عن مكان وجود الملف.
</Note>

## التبعيات

يضع `twenty app init` الحزم `twenty-sdk` و`twenty-client-sdk` و`twenty-ui` ضمن `devDependencies`، مع تثبيتها على إصدار SDK الذي يحدده إصدار CLI ذلك. احتفظ بالإصدارات المُنشأة لتطبيق جديد، وحافظ على تزامن الحزم الثلاث جميعًا عند الترقية. يمكن أن يتلقى CLI إصدارات تصحيحية بشكل مستقل، لذا لا يلزم أن يتطابق إصداره مع هذه الحزم.

يضبط `engines.twenty` المُنشأ الحد الأدنى لإصدار الخادم على الإصدار الرئيسي والفرعي الخاصين بـ SDK تلك. تُثبّت مهام سير عمل GitHub Actions المُنشأة إصدار CLI بشكل منفصل.

* يوفّر **`twenty-sdk`** تعريفات التطبيقات، ومساعدات وقت التشغيل، والتكامل مع العارض. استخدم حزمة **`twenty`** المثبّتة بشكل منفصل لأوامر CLI وأدوات البناء وإنشاء الهياكل.
* يتم استيراد **`twenty-client-sdk`** بواسطة كود تطبيقك (`CoreApiClient`، `MetadataApiClient`، `RestApiClient`)؛ لكن Twenty توفّره في وقت التشغيل — حيث تحصل عليه دوال المنطق من طبقة SDK مُولَّدة، وتحصل عليه مكوّنات الواجهة من وحدات يتم تقديمها من الخادم. يُستخدَم الإصدار المثبّت لديك فقط لفحص الأنواع (typechecking) ولبناء النشر (deploy-time build)، لذا لا يلزم أبدًا أن يتم تضمينه في حزمة النشر.

الاحتفاظ بأي من الحزمتين ضمن `dependencies` يؤدي إلى سحبها داخل حزمة وقت تشغيل التطبيق المثبّت، حيث تكون عبئًا زائدًا بلا فائدة. يُطلق `twenty app build` تحذيرًا عندما تكون أيٌّ منهما ما تزال مدرجة ضمن `dependencies`.

أضِف تبعيات وقت التشغيل الخاصة بتطبيقك (المكتبات التي تستوردها دوال المنطق لديك فعلًا في وقت التشغيل) ضمن `dependencies` كالمعتاد. حافظ على الشجرة خفيفة: تُثبَّت `dependencies` في طبقة وقت التشغيل بحد أقصى 250MB بعد فك الضغط، وتفشل عملية المزامنة أو التثبيت بخطأ في حجم الاعتمادات عند تجاوز ذلك — تنتمي مكتبات واجهة المستخدم وأدوات التطوير إلى `devDependencies`.

<PageBanner illustration="card-page-frontend-architecture" />