الانتقال إلى المحتوى الرئيسي
يبدو التطبيق الجديد الذي يتم إنشاؤه بواسطة npx create-twenty-app كما يلي:
my-twenty-app/
  package.json
  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
    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)
      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
  public/
    logo.svg                                # Static assets
  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/__tests__/اختبار وحدة بالإضافة إلى اختبار تكامل (مع إعداده العام) يقوم بمزامنة التطبيق مع خادم حقيقي.
public/أصول ثابتة (صور، خطوط) تُقدَّم مع تطبيقك.
AGENTS.md / CLAUDE.mdإرشادات لوكلاء برمجة الذكاء الاصطناعي الذين يعملون على التطبيق.
CHANGELOG.md / SETUP.mdسجل بأبرز التغييرات وتعليمات الإعداد للتطوير المحلي.
تنظيم الملفات متروك لك. المجلدات المذكورة أعلاه هي أعراف متَّبعة — يكتشف SDK الكيانات عبر تحليل AST على استدعاءات export default defineEntity(...) بغض النظر عن مكان وجود الملف.

التبعيات

ينبغي أن تكون حزمتا SDK الخاصتان بـ Twenty ضمن devDependencies، وليس ضمن dependencies:
{
  "dependencies": {},
  "devDependencies": {
    "twenty-client-sdk": "2.20.0",
    "twenty-sdk": "2.20.0",
    "twenty-ui": "1.0.0-alpha.1"
  }
}
تقوم أداة إنشاء الهيكل بتثبيت الحزمتين twenty-sdk و twenty-client-sdk على إصدارها الخاص — حافظ على تزامنهما عند الترقية.
  • توفّر twenty-sdk أداة twenty CLI وأدوات البناء/إنشاء الهياكل (scaffolding). يعمل فقط أثناء التطوير ووقت البناء، ولا يتم استيراده أبدًا في وقت تشغيل تطبيقك المنشور.
  • يتم استيراد twenty-client-sdk بواسطة كود تطبيقك (CoreApiClient، MetadataApiClient، RestApiClient)؛ لكن Twenty توفّره في وقت التشغيل — حيث تحصل عليه دوال المنطق من طبقة SDK مُولَّدة، وتحصل عليه مكوّنات الواجهة من وحدات يتم تقديمها من الخادم. يُستخدَم الإصدار المثبّت لديك فقط لفحص الأنواع (typechecking) ولبناء النشر (deploy-time build)، لذا لا يلزم أبدًا أن يتم تضمينه في حزمة النشر.
الاحتفاظ بأي من الحزمتين ضمن dependencies يؤدي إلى سحبها داخل حزمة وقت تشغيل التطبيق المثبّت، حيث تكون عبئًا زائدًا بلا فائدة. يُطلق twenty dev:build تحذيرًا عندما تكون أيٌّ منهما ما تزال مدرجة ضمن dependencies. أضِف تبعيات وقت التشغيل الخاصة بتطبيقك (المكتبات التي تستوردها دوال المنطق لديك فعلًا في وقت التشغيل) ضمن dependencies كالمعتاد.