Voraussetzungen
- Node.js 24+ — Hier herunterladen
- Yarn 4 — Wird mit Node.js über Corepack mitgeliefert. Aktivieren Sie es:
corepack enable
- Docker — Hier herunterladen. Erforderlich, um einen lokalen Twenty-Server auszuführen. Überspringen Sie dies, wenn Twenty bereits anderswo läuft.
Das Erstellen einer Twenty-App umfasst drei Phasen. Das Scaffolding-Tool fasst sie zu einem einzigen Happy-Path-Befehl zusammen, aber jede Phase ist ein eigenes Konzept — wenn etwas fehlschlägt, hilft Ihnen das Wissen, in welcher Phase Sie sich befinden, zu erkennen, was zu beheben ist.
| Phase | Was Sie tun | Tool | Ergebnis |
|---|
| 1. Gerüst erstellen | Den Quellcode der App erzeugen | npx create-twenty-app | Ein TypeScript-Projekt auf der Festplatte |
| 2. Server starten | Einen Twenty-Server starten, in den synchronisiert wird | Docker + yarn twenty server | Eine laufende Twenty-Instanz |
| 3. Synchronisieren | Ihren Code live mit dem Server synchronisieren | yarn twenty dev | Ihre Änderungen erscheinen in der Benutzeroberfläche |
Phase 1 — Projektgerüst erstellen
Erstellen Sie eine neue App aus der Vorlage:
npx create-twenty-app@latest my-twenty-app
my-twenty-app/ erzeugt, mit einer Startdatei application-config.ts, einer Standardrolle, einem CI-Workflow und einem Integrationstest.
Nach dieser Phase: Sie haben den Quellcode einer App auf Ihrem Rechner. Es läuft noch nicht — das ist Phase 2.
Phase 2 — Einen lokalen Twenty-Server starten
Ihre App benötigt einen Twenty-Server, in den sie synchronisieren kann. Der Server ist eine vollständige Twenty-Instanz — UI, GraphQL-API, PostgreSQL — die lokal in Docker läuft. Ihr lokaler Code lädt seine Definitionen auf diesen Server hoch, wodurch sie in der Benutzeroberfläche erscheinen.
Das Scaffolding-Tool bietet an, einen für Sie zu starten:
Möchten Sie eine lokale Twenty-Instanz einrichten?
- Ja (empfohlen) — lädt das Docker-Image
twentycrm/twenty-app-dev herunter und startet es auf Port 2020. Stellen Sie sicher, dass Docker läuft.
- Nein — wählen Sie dies, wenn Sie bereits einen Twenty-Server haben, mit dem Sie sich verbinden möchten. Sie können die Verbindung später mit
yarn twenty remote add herstellen.
Sobald der Server läuft, öffnet sich ein Browser zur Anmeldung. Verwenden Sie das vorab eingerichtete Demo-Konto:
- E-Mail:
tim@apple.dev
- Passwort:
tim@apple.dev
Klicken Sie auf dem nächsten Bildschirm auf Authorize — dadurch erhält die CLI Zugriff auf Ihren Arbeitsbereich.
Ihr Terminal bestätigt, dass alles eingerichtet ist.
Nach dieser Phase: Sie haben einen laufenden Twenty-Server unter http://localhost:2020, und Ihre CLI ist autorisiert, mit ihm zu synchronisieren.
Wenn Docker nicht installiert ist oder nicht läuft, zeigt das Scaffolding-Tool den richtigen Startbefehl für Ihr Betriebssystem an. Sobald Docker läuft, können Sie mit yarn twenty server start fortfahren — ein erneutes Scaffolding ist nicht nötig.
Phase 3 — Ihre Änderungen synchronisieren
Das ist die innere Schleife, in der Sie die meiste Zeit verbringen werden.
cd my-twenty-app
yarn twenty dev
src/, baut bei jeder Änderung neu und synchronisiert das Ergebnis mit dem Server. Bearbeiten Sie eine Datei, speichern Sie, und innerhalb einer Sekunde spiegelt der Server die Änderung wider. Sie sehen eine Live-Statusanzeige in Ihrem Terminal.
Für ausführlichere Ausgaben (Build-Protokolle, Sync-Anfragen, Fehlerspuren) fügen Sie --verbose hinzu.
Öffnen Sie http://localhost:2020/settings/applications#developer. Unter Your Apps sollte Ihre App angezeigt werden.
Klicken Sie auf My twenty app, um die Anwendungsregistrierung anzuzeigen — ein serverseitiger Datensatz, der Ihre App beschreibt (Name, Bezeichner, OAuth-Anmeldedaten, Quelle). Eine Registrierung kann in mehreren Arbeitsbereichen auf demselben Server installiert werden.
Klicken Sie auf View installed app, um die Installation im Arbeitsbereich anzuzeigen. Die Registerkarte About zeigt die Version und Verwaltungsoptionen.
Nach dieser Phase: Sie haben eine Live-Entwicklungsschleife. Bearbeiten Sie eine beliebige Datei in src/, und sie erscheint in der Benutzeroberfläche.
Einmalige Synchronisierung für CI und Skripte
Verwenden Sie --once, um einen einzelnen Build + Sync auszuführen und zu beenden — gleiche Pipeline, kein Watcher:
| Befehl | Verhalten | Wann verwenden |
|---|
yarn twenty dev | Überwacht und synchronisiert bei jeder Änderung erneut. Läuft, bis Sie es stoppen. | Interaktive lokale Entwicklung. |
yarn twenty dev --once | Einmaliger Build + Sync, beendet sich mit 0 bei Erfolg, mit 1 bei Fehler. | CI, Pre-Commit-Hooks, KI-Agenten, skriptgesteuerte Workflows. |
Der Dev-Modus ist nur auf Twenty-Instanzen verfügbar, die im Entwicklungsmodus laufen (NODE_ENV=development). Produktionsinstanzen lehnen Dev-Sync-Anfragen ab — verwenden Sie yarn twenty deploy, um auf Produktionsserver bereitzustellen. Siehe Apps veröffentlichen.
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 | Benutzerdefinierte Datenmodelle (Postkarte, Rechnung usw.) mit typisierten Feldern |
| Logikfunktionen | Serverseitiges TypeScript, ausgelöst durch HTTP-Routen, Cron-Zeitpläne oder Datenbankereignisse |
| 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 |
| Seitenlayouts | Benutzerdefinierte Datensatz-Detailseiten mit Tabs und Widgets |
Projektstruktur
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
__tests__/
setup-test.ts
app-install.integration-test.ts
.github/workflows/ci.yml # GitHub Actions
public/ # Static assets
vitest.config.ts # Test runner config
tsconfig.json, tsconfig.spec.json
.nvmrc, .yarnrc.yml, .oxlintrc.json
README.md, LLMS.md
| Datei / Ordner | Zweck |
|---|
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 Metadaten (Anzeigename, Beschreibung). |
src/__tests__/ | Integrationstests (Setup + Beispieltest). |
public/ | Statische Assets (Bilder, Schriftarten), die mit Ihrer App ausgeliefert werden. |
Mit einem Beispiel beginnen
Verwenden Sie --example, um mit einem vollständigeren Projekt zu starten (benutzerdefinierte Objekte, Felder, Logikfunktionen, Front-End-Komponenten):
npx create-twenty-app@latest my-twenty-app --example postcard
yarn twenty add erzeugen — siehe Apps entwickeln.
Lokalen Server verwalten
Verwenden Sie yarn twenty server, um den lokalen Twenty-Container zu steuern:
| Befehl | Was es tut |
|---|
yarn twenty server start | 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 | URL, Version und Anmeldedaten anzeigen |
yarn twenty server logs | Serverprotokolle streamen |
yarn twenty server reset | Alle Daten löschen und neu starten |
yarn twenty server upgrade | Das neueste twenty-app-dev-Image herunterladen |
yarn twenty server upgrade 2.2.0 | Auf eine bestimmte Version aktualisieren |
twenty-app-dev-data für PostgreSQL, twenty-app-dev-storage für Dateien). Verwenden Sie reset, um alles zu löschen.
Aktualisieren des Server-Images
yarn twenty server upgrade lädt das neueste Image herunter, vergleicht die Digests und erstellt den Container nur neu, wenn sich tatsächlich etwas geändert hat. Die Volumes bleiben erhalten — nur der Container wird ersetzt. Wenn ein neues Image heruntergeladen wurde und der Container lief, startet das Upgrade automatisch einen neuen Container; führen Sie anschließend yarn twenty server start aus, um zu warten, bis er betriebsbereit ist.
yarn twenty server upgrade # Latest
yarn twenty server upgrade 2.2.0 # Specific version
yarn twenty server status (dies zeigt die im Container enthaltene APP_VERSION an).
Eine parallele Testinstanz ausführen
Übergeben Sie --test an jeden server-Befehl, um eine zweite, vollständig isolierte Instanz zu verwalten — nützlich für Integrationstests oder Experimente, ohne Ihre Hauptentwicklungsdaten anzutasten:
| Befehl | Was es tut |
|---|
yarn twenty server start --test | Die Testinstanz starten (standardmäßig Port 2021) |
yarn twenty server stop --test | Anhalten |
yarn twenty server status --test | Status anzeigen |
yarn twenty server logs --test | Protokolle streamen |
yarn twenty server reset --test | Daten löschen |
yarn twenty server upgrade --test | Image aktualisieren |
twenty-app-dev-test), eigene Volumes (twenty-app-dev-test-data, twenty-app-dev-test-storage) und eine eigene Konfiguration — sie läuft parallel zu Ihrer Hauptinstanz ohne Konflikte. Kombinieren Sie --test mit --port, um den Port 2021 zu überschreiben.
Manuelle Einrichtung (ohne Scaffolder)
Überspringen Sie das Scaffolding-Tool, wenn Sie das SDK zu einem bestehenden Projekt hinzufügen:
yarn add twenty-sdk twenty-client-sdk
package.json das Skript hinzu:
{
"scripts": {
"twenty": "twenty"
}
}
yarn twenty dev, yarn twenty server start und den Rest ausführen.
Installieren Sie twenty-sdk nicht global — fixieren Sie es pro Projekt, damit jede App ihre eigene Version verwendet.
Fehlerbehebung
- Docker-Fehler — Stellen Sie sicher, dass Docker Desktop (oder der Daemon) läuft, bevor Sie
yarn twenty server start ausführen. Die Fehlermeldung zeigt den richtigen Startbefehl für Ihr Betriebssystem an.
- Falsche Node-Version — 24+ erforderlich. Prüfen Sie mit
node -v.
- Yarn 4 fehlt — Führen Sie
corepack enable aus.
- Abhängigkeiten defekt —
rm -rf node_modules && yarn install.
Hängen Sie fest? Bitten Sie im Twenty-Discord um Hilfe.
