Concepte

Aplicațiile Twenty sunt pachete TypeScript care vă extind spațiul de lucru cu obiecte personalizate, logică, componente UI și capabilități AI. Acestea rulează pe platforma Twenty, cu izolare completă (sandboxing) și controale de permisiuni.

Cum funcționează aplicațiile

O aplicație este o colecție de entități declarate folosind funcțiile defineEntity() din pachetul twenty-sdk. SDK-ul detectează aceste declarații prin analiză AST în timpul construirii și produce un manifest — o descriere completă a ceea ce aplicația dvs. adaugă unui spațiu de lucru. Aceste funcții validează configurația în timpul build-ului și oferă completare automată în IDE și siguranța tipurilor.

your-app/
├── src/
│   ├── application-config.ts    ← defineApplication (required, one per app)
│   ├── roles/                   ← defineRole
│   ├── objects/                 ← defineObject
│   ├── fields/                  ← defineField
│   ├── logic-functions/         ← defineLogicFunction
│   ├── front-components/        ← defineFrontComponent
│   ├── skills/                  ← defineSkill
│   ├── agents/                  ← defineAgent
│   ├── views/                   ← defineView
│   ├── navigation-menu-items/   ← defineNavigationMenuItem
│   └── page-layouts/            ← definePageLayout
├── public/                      ← Static assets (images, icons)
└── package.json

Organizarea fișierelor ține de dvs. Detectarea entităților este bazată pe AST — SDK-ul găsește apelurile export default defineEntity(...) indiferent unde se află fișierul. Structura de foldere de mai sus este o convenție, nu o cerință.

Tipuri de entități

Entitate	Scop	Documentație
Aplicație	Identitatea aplicației, rolul implicit, variabile	Application Config
Rol	Seturi de permisiuni pentru obiecte și câmpuri	Roles & Permissions
Obiect	Tipuri de înregistrări personalizate cu câmpuri	Objects
Câmp	Adăugați câmpuri la obiecte din alte aplicații	Extending Objects
Relație	Legături bidirecționale între obiecte	Relations
Funcție logică	TypeScript pe partea de server cu declanșatoare	Funcții logice
Abilitate	Instrucțiuni reutilizabile pentru agenți AI	Abilități și agenți
Agent	Agenți AI cu prompturi personalizate	Abilități și agenți
Furnizor de conexiune	Date de autentificare OAuth pentru API-uri terțe	Connections
Vizualizare	Vizualizări preconfigurate ale listelor de înregistrări	Views
Element de meniu de navigare	Intrări personalizate în bara laterală	Navigation Menu Items
Layout pagină	File și widgeturi pe pagina de detalii a unei înregistrări	Page Layouts
Componentă front-end	Interfață React izolată (sandboxed) în Twenty	Componente front-end
Element din meniul de comenzi	Acțiuni rapide și intrări Cmd+K	Command Menu Items

Izolare (sandboxing)

Funcțiile logice rulează în procese Node.js izolate pe server. Acestea accesează datele doar prin clientul API tipizat, limitat de permisiunile rolului aplicației.
Componentele front-end rulează în Web Workers folosind Remote DOM — izolate de pagina principală, dar randând elemente DOM native (nu iframes). Acestea comunică cu Twenty printr-un API al gazdei bazat pe transmiterea de mesaje.
Permisiunile sunt aplicate la nivelul API-ului. Tokenul de rulare (TWENTY_APP_ACCESS_TOKEN) este derivat din rolul definit în defineApplication().

Ciclul de viață al aplicației

┌─────────────────────────────────────────────────────────┐
│ Development                                             │
│   npx create-twenty-app → yarn twenty dev (live sync)   │
├─────────────────────────────────────────────────────────┤
│ Build & Deploy                                          │
│   yarn twenty dev:build → yarn twenty app:publish        │
├─────────────────────────────────────────────────────────┤
│ Install flow                                            │
│   upload → [pre-install] → metadata migration →         │
│   generate SDK → [post-install] → … → [uninstall]       │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘

yarn twenty dev — monitorizează fișierele sursă și sincronizează în timp real modificările către un server Twenty conectat. Clientul API tipizat este regenerat automat atunci când schema se schimbă.
yarn twenty dev:build — compilează TypeScript, împachetează funcțiile logice și componentele front-end cu esbuild și produce un manifest.
Hook-uri pre/post-instalare și dezinstalare — funcții opționale care rulează în timpul instalării sau chiar înainte de eliminare. Vezi Install Hooks pentru detalii.

Pașii următori

Configurare

Identitatea aplicației, rolul implicit și hook-urile de instalare și dezinstalare.

Date

Obiecte, câmpuri și relații bidirecționale.

Logică

Funcții logice, abilități, agenți și conexiuni OAuth.

Aspect

Vizualizări, navigare, layouturi de pagină, componente front-end.

Operațiuni

CLI, testare, remote-uri, CI și publicarea aplicației.

Prezentare generală

Aplicații

API

Autogazda

Contribuie

Cum funcționează aplicațiile

Tipuri de entități

Izolare (sandboxing)

Ciclul de viață al aplicației

Pașii următori

Configurare

Date

Logică

Aspect

Operațiuni

​Cum funcționează aplicațiile

​Tipuri de entități

​Izolare (sandboxing)

​Ciclul de viață al aplicației

​Pașii următori

Configurare

Date

Logică

Aspect

Operațiuni

Cum funcționează aplicațiile

Tipuri de entități

Izolare (sandboxing)

Ciclul de viață al aplicației

Pașii următori