274 lines
16 KiB
Plaintext
274 lines
16 KiB
Plaintext
---
|
|
title: Erste Schritte
|
|
icon: rocket
|
|
description: Erstellen Sie in wenigen Minuten Ihre erste Twenty-App.
|
|
---
|
|
|
|
## Voraussetzungen
|
|
|
|
* **Node.js 24+** — [Hier herunterladen](https://nodejs.org/)
|
|
* **Yarn 4** — Wird mit Node.js über Corepack mitgeliefert. Aktivieren Sie es: `corepack enable`
|
|
* **Docker** — [Hier herunterladen](https://www.docker.com/products/docker-desktop/). 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:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app
|
|
```
|
|
|
|
Sie werden nach einem Namen und einer Beschreibung gefragt — drücken Sie **Enter** für die Standardwerte. Dadurch wird ein TypeScript-Projekt in `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.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Soll die lokale Instanz gestartet werden?" />
|
|
</div>
|
|
|
|
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`
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/login.png" alt="Twenty-Anmeldebildschirm" />
|
|
</div>
|
|
|
|
Klicken Sie auf dem nächsten Bildschirm auf **Authorize** — dadurch erhält die CLI Zugriff auf Ihren Arbeitsbereich.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty-CLI-Autorisierungsbildschirm" />
|
|
</div>
|
|
|
|
Ihr Terminal bestätigt, dass alles eingerichtet ist.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App-Gerüst erfolgreich erstellt" />
|
|
</div>
|
|
|
|
**Nach dieser Phase:** Sie haben einen laufenden Twenty-Server unter [http://localhost:2020](http://localhost:2020), und Ihre CLI ist autorisiert, mit ihm zu synchronisieren.
|
|
|
|
<Note>
|
|
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.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Phase 3 — Ihre Änderungen synchronisieren
|
|
|
|
Das ist die innere Schleife, in der Sie die meiste Zeit verbringen werden.
|
|
|
|
```bash filename="Terminal"
|
|
cd my-twenty-app
|
|
yarn twenty dev
|
|
```
|
|
|
|
Dies überwacht `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.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/dev.png" alt="Terminalausgabe im Dev-Modus" />
|
|
</div>
|
|
|
|
Öffnen Sie [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Unter **Your Apps** sollte Ihre App angezeigt werden.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Liste "Your Apps", die "My twenty app" anzeigt" />
|
|
</div>
|
|
|
|
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.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Details der Anwendungsregistrierung" />
|
|
</div>
|
|
|
|
Klicken Sie auf **View installed app**, um die Installation im Arbeitsbereich anzuzeigen. Die Registerkarte **About** zeigt die Version und Verwaltungsoptionen.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Installierte App" />
|
|
</div>
|
|
|
|
**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:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty dev --once
|
|
```
|
|
|
|
| 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. |
|
|
|
|
Beide Modi benötigen einen Server im Entwicklungsmodus und eine authentifizierte Remote-Verbindung.
|
|
|
|
<Warning>
|
|
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](/l/de/developers/extend/apps/publishing).
|
|
</Warning>
|
|
|
|
---
|
|
|
|
## 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 |
|
|
|
|
Vollständige Referenz: [Apps entwickeln](/l/de/developers/extend/apps/building).
|
|
|
|
## Projektstruktur
|
|
|
|
```text filename="my-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
|
|
__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):
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app --example postcard
|
|
```
|
|
|
|
Die Beispiele befinden sich unter [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples). Sie können auch einzelne Entitäten in einem bestehenden Projekt mit `yarn twenty add` erzeugen — siehe [Apps entwickeln](/l/de/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add).
|
|
|
|
---
|
|
|
|
## 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 |
|
|
|
|
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.
|
|
|
|
### 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.
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server upgrade # Latest
|
|
yarn twenty server upgrade 2.2.0 # Specific version
|
|
```
|
|
|
|
Überprüfen Sie die laufende Version mit `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 |
|
|
|
|
Die Testinstanz hat ihren eigenen Container (`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:
|
|
|
|
```bash filename="Terminal"
|
|
yarn add twenty-sdk twenty-client-sdk
|
|
```
|
|
|
|
Fügen Sie der `package.json` das Skript hinzu:
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"scripts": {
|
|
"twenty": "twenty"
|
|
}
|
|
}
|
|
```
|
|
|
|
Sie können jetzt `yarn twenty dev`, `yarn twenty server start` und den Rest ausführen.
|
|
|
|
<Note>
|
|
Installieren Sie `twenty-sdk` nicht global — fixieren Sie es pro Projekt, damit jede App ihre eigene Version verwendet.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## 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](https://discord.com/channels/1130383047699738754/1130386664812982322) um Hilfe.
|