Konzepte

Wie Twenty-Apps funktionieren – Entitätenmodell, Sandboxing und Installationslebenszyklus.

Twenty-Apps sind TypeScript-Pakete, die Ihren Arbeitsbereich mit benutzerdefinierten Objekten, Logik, UI-Komponenten und KI-Funktionen erweitern. Sie laufen auf der Twenty-Plattform mit vollständigem Sandboxing und Berechtigungsverwaltung.

​

Wie Apps funktionieren

Eine App ist eine Sammlung von Entitäten, die mithilfe von defineEntity()-Funktionen aus dem Paket twenty-sdk deklariert werden. Das SDK erkennt diese Deklarationen zur Build-Zeit per AST-Analyse und erzeugt ein Manifest — eine vollständige Beschreibung dessen, was Ihre App zu einem Arbeitsbereich hinzufügt. Diese Funktionen validieren Ihre Konfiguration zur Build-Zeit und bieten IDE-Autovervollständigung sowie Typsicherheit.

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

Die Dateiorganisation liegt bei Ihnen. Die Entitätserkennung ist AST-basiert — das SDK findet Aufrufe von export default defineEntity(...), unabhängig davon, wo sich die Datei befindet. Die obige Ordnerstruktur ist eine Konvention, keine Anforderung.

​

Entitätstypen

Entität	Zweck	Dokumentation
Anwendung	App-Identität, Standardrolle, Variablen	Anwendungskonfiguration
Rolle	Berechtigungssätze für Objekte und Felder	Rollen & Berechtigungen
Objekt	Benutzerdefinierte Datensatztypen mit Feldern	Objekte
Feld	Felder zu Objekten aus anderen Apps hinzufügen	Objekte erweitern
Beziehung	Bidirektionale Verknüpfungen zwischen Objekten	Beziehungen
Logikfunktion	Serverseitiges TypeScript mit Triggern	Logikfunktionen
Skill	Wiederverwendbare Anweisungen für KI-Agenten	Skills & Agenten
Agent	KI-Assistenten mit benutzerdefinierten Prompts	Skills & Agenten
Verbindungsanbieter	OAuth-Zugangsdaten für Drittanbieter-APIs	Verbindungen
Ansicht	Vorkonfigurierte Listenansichten für Datensätze	Ansichten
Navigationsmenüeintrag	Benutzerdefinierte Seitenleisten-Einträge	Navigationsmenüeinträge
Seitenlayout	Tabs und Widgets auf der Detailseite eines Datensatzes	Seiten-Layouts
Frontend-Komponente	Isolierte React-UI innerhalb von Twenty	Frontend-Komponenten
Befehlsmenü-Eintrag	Schnellaktionen und Cmd+K-Einträge	Befehlsmenü-Einträge

​

Sandboxing

• Logikfunktionen laufen in isolierten Node.js-Prozessen auf dem Server. Sie greifen nur über den typisierten API-Client auf Daten zu, begrenzt durch die Rollenberechtigungen der App.
• Frontend-Komponenten laufen in Web Workers mit Remote DOM — von der Hauptseite isoliert, rendern aber native DOM-Elemente (keine iframes). Sie kommunizieren über eine Message-Passing-Host-API mit Twenty.
• Berechtigungen werden auf API-Ebene durchgesetzt. Das Laufzeit-Token (TWENTY_APP_ACCESS_TOKEN) wird aus der in defineApplication() definierten Rolle abgeleitet.

​

App-Lebenszyklus

┌─────────────────────────────────────────────────────────┐
│ 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]                         │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘

• yarn twenty dev — überwacht Ihre Quelldateien und synchronisiert Änderungen in Echtzeit mit einem verbundenen Twenty-Server. Der typisierte API-Client wird automatisch neu erzeugt, wenn sich das Schema ändert.
• yarn twenty dev:build — kompiliert TypeScript, bündelt Logikfunktionen und Frontend-Komponenten mit esbuild und erzeugt ein Manifest.
• Pre/Post-Install-Hooks — optionale Funktionen, die während der Installation ausgeführt werden. Details finden Sie unter Install Hooks.

​

Nächste Schritte

Konfiguration

App-Identität, Standardrolle und Install-Hooks.

Daten

Objekte, Felder und bidirektionale Relationen.

Logik

Logikfunktionen, Skills, Agenten und OAuth-Verbindungen.

Layout

Ansichten, Navigation, Seiten-Layouts, Frontend-Komponenten.

Operationen

CLI, Tests, Remotes, CI und das Veröffentlichen Ihrer App.