Erste Schritte

Erstellen Sie in wenigen Minuten Ihre erste Twenty-App.

Apps befinden sich derzeit in der Alpha-Phase. Die Funktion ist funktionsfähig, entwickelt sich jedoch noch weiter.

​

Was sind Apps?

Apps ermöglichen es Ihnen, Twenty mit benutzerdefinierten Objekten, Feldern, Logikfunktionen, Frontend-Komponenten, KI-Fähigkeiten und mehr zu erweitern — alles als Code verwaltet. Anstatt alles über die UI zu konfigurieren, definieren Sie Ihr Datenmodell und Ihre Logik in TypeScript und stellen es in einem oder mehreren Workspaces bereit.

​

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Folgendes auf Ihrem Rechner installiert ist:

• Node.js 24+ — Hier herunterladen
• Yarn 4 — Wird mit Node.js über Corepack mitgeliefert. Aktivieren Sie es, indem Sie corepack enable ausführen
• Docker — Hier herunterladen. Erforderlich, um eine lokale Twenty-Instanz auszuführen. Nicht erforderlich, wenn bereits ein Twenty-Server läuft.

​

Erstellen Sie Ihre erste App

​

App-Gerüst erstellen

Öffnen Sie ein Terminal und führen Sie Folgendes aus:

npx create-twenty-app@latest my-twenty-app

Sie werden aufgefordert, einen Namen und eine Beschreibung für Ihre App einzugeben. Drücken Sie Enter, um die Standardwerte zu übernehmen.

Dadurch wird ein neuer Ordner namens my-twenty-app mit allem erstellt, was Sie benötigen.

​

Lokale Twenty-Instanz einrichten

Das Scaffolding-Tool fragt:

Möchten Sie eine lokale Twenty-Instanz einrichten?

• Geben Sie yes ein (empfohlen) — Dadurch wird das Docker-Image twenty-app-dev heruntergeladen und ein lokaler Twenty-Server auf Port 2020 gestartet. Stellen Sie sicher, dass Docker läuft, bevor Sie fortfahren.
• Geben Sie no ein — Wählen Sie dies, wenn bereits ein Twenty-Server lokal läuft.

​

Melden Sie sich bei Ihrem Arbeitsbereich an

Anschließend öffnet sich ein Browserfenster mit der Twenty-Anmeldeseite. Melden Sie sich mit dem vorab eingerichteten Demo-Konto an:

• E-Mail: [e-mail]
• Passwort: [e-mail]

​

Autorisieren Sie die App

Nach der Anmeldung sehen Sie einen Autorisierungsbildschirm. Dadurch kann Ihre App mit Ihrem Arbeitsbereich interagieren.

Klicken Sie auf Authorize, um fortzufahren.

Nach der Autorisierung bestätigt Ihr Terminal, dass alles eingerichtet ist.

​

Beginnen Sie mit der Entwicklung

Wechseln Sie in Ihren neuen App-Ordner und starten Sie den Entwicklungsserver:

cd my-twenty-app
yarn twenty dev

Dadurch werden Ihre Quelldateien überwacht, bei jeder Änderung neu gebaut und Ihre App automatisch mit dem lokalen Twenty-Server synchronisiert. In Ihrem Terminal sollte eine Live-Statusanzeige angezeigt werden.

Für ausführlichere Ausgaben (Build-Protokolle, Sync-Anfragen, Fehlerspuren) verwenden Sie das Flag --verbose:

yarn twenty dev --verbose

Der Dev-Modus ist nur auf Twenty-Instanzen verfügbar, die im Entwicklungsmodus laufen (NODE_ENV=development). Produktionsinstanzen lehnen Dev-Synchronisierungsanfragen ab. Verwenden Sie yarn twenty deploy, um auf Produktionsservern bereitzustellen — Details finden Sie unter Apps veröffentlichen.

​

Sehen Sie sich Ihre App in Twenty an

Öffnen Sie http://localhost:2020/settings/applications#developer in Ihrem Browser. Navigieren Sie zu Settings > Apps und wählen Sie die Registerkarte Developer. Unter Your Apps sollte Ihre App aufgeführt sein:

Klicken Sie auf My twenty app, um die Anwendungsregistrierung zu öffnen. Eine Registrierung ist ein Servereintrag, der Ihre App beschreibt — ihren Namen, den eindeutigen Bezeichner, OAuth-Zugangsdaten und die Quelle (lokal, npm oder Tarball). Sie befindet sich auf dem Server, nicht in einem bestimmten Arbeitsbereich. Wenn Sie eine App in einen Arbeitsbereich installieren, erstellt Twenty eine arbeitsbereichsbezogene Anwendung, die auf diese Registrierung verweist. Eine Registrierung kann in mehreren Arbeitsbereichen auf demselben Server installiert werden.

Klicken Sie auf View installed app, um die installierte App anzuzeigen. Die Registerkarte About zeigt die aktuelle Version und Verwaltungsoptionen:

Wechseln Sie zur Registerkarte Content, um alles zu sehen, was Ihre App bereitstellt — Objekte, Felder, Logikfunktionen und Agenten:

Alles erledigt! Bearbeiten Sie eine beliebige Datei in src/, und die Änderungen werden automatisch übernommen.

---

​

Was Sie erstellen können

Apps bestehen aus Entitäten — jede ist als TypeScript-Datei mit einem einzigen export default definiert:

Entität	Was sie macht
Objekte & Felder	Definieren Sie benutzerdefinierte Datenmodelle (wie Post Card, Invoice) mit typisierten Feldern
Logikfunktionen	Serverseitige TypeScript-Funktionen, die durch HTTP-Routen, Cron-Zeitpläne oder Datenbankereignisse ausgelöst werden
Frontend-Komponenten	React-Komponenten, die in der UI von Twenty gerendert werden (Seitenleiste, Widgets, Befehlsmenü)
Fähigkeiten & Agenten	KI-Funktionen — wiederverwendbare Anweisungen und autonome Assistenten
Ansichten & Navigation	Vorkonfigurierte Listenansichten und Seitenleisteneinträge für Ihre Objekte
Seitenlayouts	Benutzerdefinierte Datensatz-Detailseiten mit Tabs und Widgets

Wechseln Sie zu Apps erstellen für eine ausführliche Anleitung zu jedem Entitätstyp.

---

​

Projektstruktur

Der Scaffolder erzeugt die folgende Verzeichnisstruktur:

my-twenty-app/
  package.json
  yarn.lock
  .gitignore
  .nvmrc
  .yarnrc.yml
  .oxlintrc.json
  tsconfig.json
  tsconfig.spec.json                          # TypeScript config for tests
  vitest.config.ts                            # Vitest test runner configuration
  LLMS.md
  README.md
  .github/
    └── workflows/
        └── ci.yml                            # GitHub Actions CI workflow
  public/                                     # Public assets (images, fonts, etc.)
  src/
  ├── application-config.ts                   # Required — main application configuration
  ├── default-role.ts                         # Default role for logic functions
  ├── constants/
  │   └── universal-identifiers.ts            # Auto-generated UUIDs and app metadata
  └── __tests__/
      ├── setup-test.ts                       # Test setup (server health check, config)
      └── app-install.integration-test.ts     # Integration test

​

Mit einem Beispiel beginnen

Um mit einem umfassenderen Beispiel mit benutzerdefinierten Objekten, Feldern, Logikfunktionen, Frontend-Komponenten und mehr zu starten, verwenden Sie die Option --example:

npx create-twenty-app@latest my-twenty-app --example postcard

Die Beispiele stammen aus dem Verzeichnis twenty-apps/examples auf GitHub. Sie können auch einzelne Entitäten in einem bestehenden Projekt mit yarn twenty add erzeugen (siehe Apps erstellen).

​

Wichtige Dateien

Datei / Ordner	Zweck
package.json	Deklariert den App-Namen, die Version und Abhängigkeiten. Enthält ein twenty-Skript, sodass Sie yarn twenty help ausführen können, um alle Befehle anzuzeigen.
src/application-config.ts	Erforderlich. Die Hauptkonfigurationsdatei für Ihre App.
src/default-role.ts	Standardrolle, die steuert, worauf Ihre Logikfunktionen zugreifen können.
src/constants/universal-identifiers.ts	Automatisch erzeugte UUIDs und App-Metadaten (Anzeigename, Beschreibung).
src/__tests__/	Integrationstests (Setup + Beispieltest).
public/	Statische Assets (Bilder, Schriftarten), die mit Ihrer App ausgeliefert werden.

​

Lokaler Entwicklungsserver

Der Scaffolder hat bereits einen lokalen Twenty-Server für Sie gestartet. Um ihn später zu verwalten, verwenden Sie yarn twenty server:

Befehl	Beschreibung
yarn twenty server start	Lokalen Server starten (lädt das Image bei Bedarf herunter)
yarn twenty server start --port 3030	Auf einem benutzerdefinierten Port starten
yarn twenty server stop	Server stoppen (Daten bleiben erhalten)
yarn twenty server status	Serverstatus, URL und Anmeldedaten anzeigen
yarn twenty server logs	Serverprotokolle streamen
yarn twenty server logs --lines 100	Die letzten 100 Protokollzeilen anzeigen
yarn twenty server reset	Alle Daten löschen und neu starten

Daten bleiben über Neustarts hinweg in zwei Docker-Volumes bestehen (twenty-app-dev-data für PostgreSQL, twenty-app-dev-storage für Dateien). Verwenden Sie reset, um alles zu löschen und neu zu beginnen.

Der Server erfordert, dass Docker läuft. Wenn der Fehler “Docker not running” angezeigt wird, stellen Sie sicher, dass Docker Desktop (oder der Docker-Daemon) gestartet ist.

​

Manuelle Einrichtung (ohne Scaffolder)

Wenn Sie die Einrichtung lieber selbst vornehmen möchten, anstatt create-twenty-app zu verwenden, können Sie dies in zwei Schritten tun.

1. Fügen Sie twenty-sdk und twenty-client-sdk als Abhängigkeiten hinzu:

yarn add twenty-sdk twenty-client-sdk

2. Fügen Sie Ihrer package.json ein twenty-Skript hinzu:

{
  "scripts": {
    "twenty": "twenty"
  }
}

Sie können jetzt yarn twenty dev, yarn twenty help und alle anderen Befehle ausführen.

Installieren Sie twenty-sdk nicht global. Verwenden Sie es immer als lokale Projektabhängigkeit, damit jedes Projekt seine eigene Version festlegen kann.

​

Fehlerbehebung

Wenn Probleme auftreten:

• Stellen Sie sicher, dass Docker läuft, bevor Sie das Scaffolding-Tool mit einer lokalen Instanz starten.
• Stellen Sie sicher, dass Sie Node.js 24+ verwenden (node -v zur Überprüfung).
• Stellen Sie sicher, dass Corepack aktiviert ist (corepack enable), damit Yarn 4 verfügbar ist.
• Versuchen Sie, node_modules zu löschen und yarn install erneut auszuführen, wenn Abhängigkeiten fehlerhaft erscheinen.

Hängen Sie immer noch fest? Bitten Sie im Twenty-Discord um Hilfe.