412 lines
20 KiB
Plaintext
412 lines
20 KiB
Plaintext
---
|
|
title: Erste Schritte
|
|
description: Erstellen Sie in wenigen Minuten Ihre erste Twenty-App.
|
|
---
|
|
|
|
<Warning>
|
|
Apps befinden sich derzeit in der Alpha-Phase. Die Funktion ist funktionsfähig, entwickelt sich jedoch noch weiter.
|
|
</Warning>
|
|
|
|
Apps ermöglichen es Ihnen, Twenty mit benutzerdefinierten Objekten, Feldern, Logikfunktionen, KI-Fähigkeiten und UI-Komponenten zu erweitern — alles als Code verwaltet.
|
|
|
|
## Voraussetzungen
|
|
|
|
Bevor Sie beginnen, stellen Sie sicher, dass Folgendes auf Ihrem Rechner installiert ist:
|
|
|
|
* **Node.js 24+** — [Hier herunterladen](https://nodejs.org/)
|
|
* **Yarn 4** — Wird mit Node.js über Corepack mitgeliefert. Aktivieren Sie es, indem Sie `corepack enable` ausführen
|
|
* **Docker** — [Hier herunterladen](https://www.docker.com/products/docker-desktop/). Erforderlich, um eine lokale Twenty-Instanz auszuführen. Nicht erforderlich, wenn bereits ein Twenty-Server läuft.
|
|
|
|
## Schritt 1: App-Gerüst erstellen
|
|
|
|
Öffnen Sie ein Terminal und führen Sie Folgendes aus:
|
|
|
|
```bash filename="Terminal"
|
|
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.
|
|
|
|
<Note>
|
|
Das Scaffolding-Tool unterstützt diese Flags:
|
|
|
|
* `--minimal` — erstellt nur die wesentlichen Dateien, keine Beispiele (Standard)
|
|
* `--exhaustive` — erstellt alle Beispiel-Entitäten
|
|
* `--name <name>` — legt den App-Namen fest (überspringt die Abfrage)
|
|
* `--display-name <displayName>` — legt den Anzeigenamen fest (überspringt die Abfrage)
|
|
* `--description <description>` — legt die Beschreibung fest (überspringt die Abfrage)
|
|
* `--skip-local-instance` — überspringt die Eingabeaufforderung zur Einrichtung des lokalen Servers
|
|
</Note>
|
|
|
|
## Schritt 2: 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.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Soll die lokale Instanz gestartet werden?" />
|
|
</div>
|
|
|
|
## Schritt 3: Bei Ihrem Arbeitsbereich anmelden
|
|
|
|
Anschließend öffnet sich ein Browserfenster mit der Twenty-Anmeldeseite. Melden Sie sich mit dem vorab eingerichteten Demo-Konto an:
|
|
|
|
* **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>
|
|
|
|
## Schritt 4: Die App autorisieren
|
|
|
|
Nach der Anmeldung sehen Sie einen Autorisierungsbildschirm. Dadurch kann Ihre App mit Ihrem Arbeitsbereich interagieren.
|
|
|
|
Klicken Sie auf **Authorize**, um fortzufahren.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Twenty-CLI-Autorisierungsbildschirm" />
|
|
</div>
|
|
|
|
Nach der Autorisierung bestätigt Ihr Terminal, dass alles eingerichtet ist.
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App-Gerüst erfolgreich erstellt" />
|
|
</div>
|
|
|
|
## Schritt 5: Mit der Entwicklung beginnen
|
|
|
|
Wechseln Sie in Ihren neuen App-Ordner und starten Sie den Entwicklungsserver:
|
|
|
|
```bash filename="Terminal"
|
|
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`:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty dev --verbose
|
|
```
|
|
|
|
<Warning>
|
|
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](/l/de/developers/extend/apps/publishing).
|
|
</Warning>
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/dev.jpg" alt="Terminalausgabe im Dev-Modus" />
|
|
</div>
|
|
|
|
## Schritt 6: Ihre App in Twenty ansehen
|
|
|
|
Öffnen Sie [http://localhost:2020/settings/applications#developer](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:
|
|
|
|
<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** 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.
|
|
|
|
<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 installierte App anzuzeigen. Die Registerkarte **About** zeigt die aktuelle Version und Verwaltungsoptionen:
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Installierte App — Registerkarte About" />
|
|
</div>
|
|
|
|
Wechseln Sie zur Registerkarte **Content**, um alles zu sehen, was Ihre App bereitstellt — Objekte, Felder, Logikfunktionen und Agenten:
|
|
|
|
<div style={{textAlign: 'center'}}>
|
|
<img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="Installierte App — Registerkarte Content" />
|
|
</div>
|
|
|
|
Alles erledigt! Bearbeiten Sie eine beliebige Datei in `src/`, und die Änderungen werden automatisch übernommen.
|
|
|
|
Wechseln Sie zu [Apps erstellen](/l/de/developers/extend/apps/building) für eine ausführliche Anleitung zum Erstellen von Objekten, Logikfunktionen, Frontend-Komponenten, Skills und mehr.
|
|
|
|
---
|
|
|
|
## Projektstruktur
|
|
|
|
Das Scaffolding-Tool erzeugt die folgende Verzeichnisstruktur (gezeigt im Modus `--exhaustive`, der Beispiele für jeden Entitätstyp enthält):
|
|
|
|
```text filename="my-twenty-app/"
|
|
my-twenty-app/
|
|
package.json
|
|
yarn.lock
|
|
.gitignore
|
|
.nvmrc
|
|
.yarnrc.yml
|
|
.yarn/
|
|
install-state.gz
|
|
.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
|
|
├── __tests__/
|
|
│ ├── setup-test.ts # Test setup (server health check, config)
|
|
│ └── app-install.integration-test.ts # Example integration test
|
|
├── roles/
|
|
│ └── default-role.ts # Default role for logic functions
|
|
├── objects/
|
|
│ └── example-object.ts # Example custom object definition
|
|
├── fields/
|
|
│ └── example-field.ts # Example standalone field definition
|
|
├── logic-functions/
|
|
│ ├── hello-world.ts # Example logic function
|
|
│ ├── create-hello-world-company.ts # Example logic function using CoreApiClient
|
|
│ ├── pre-install.ts # Runs before installation
|
|
│ └── post-install.ts # Runs after installation
|
|
├── front-components/
|
|
│ └── hello-world.tsx # Example front component
|
|
├── page-layouts/
|
|
│ └── example-record-page-layout.ts # Example page layout with front component
|
|
├── views/
|
|
│ └── example-view.ts # Example saved view definition
|
|
├── navigation-menu-items/
|
|
│ └── example-navigation-menu-item.ts # Example sidebar navigation link
|
|
├── skills/
|
|
│ └── example-skill.ts # Example AI agent skill definition
|
|
└── agents/
|
|
└── example-agent.ts # Example AI agent definition
|
|
```
|
|
|
|
Standardmäßig (`--minimal`) werden nur die Kerndateien erstellt: `application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` und `logic-functions/post-install.ts`. Verwenden Sie `--exhaustive`, um alle oben gezeigten Beispieldateien einzuschließen.
|
|
|
|
### 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/roles/` | Definiert Rollen, die steuern, worauf Ihre Logikfunktionen zugreifen können. |
|
|
| `src/logic-functions/` | Serverseitige Funktionen, die durch Routen, Cron-Zeitpläne oder Datenbankereignisse ausgelöst werden. |
|
|
| `src/front-components/` | React-Komponenten, die innerhalb der Twenty-UI gerendert werden. |
|
|
| `src/objects/` | Benutzerdefinierte Objektdefinitionen zur Erweiterung Ihres Datenmodells. |
|
|
| `src/fields/` | Benutzerdefinierte Felder, die vorhandenen Objekten hinzugefügt werden. |
|
|
| `src/views/` | Konfigurationen gespeicherter Ansichten. |
|
|
| `src/navigation-menu-items/` | Benutzerdefinierte Links in der Seitenleisten-Navigation. |
|
|
| `src/skills/` | Skills, die die KI-Agenten von Twenty erweitern. |
|
|
| `src/agents/` | KI-Agenten mit benutzerdefinierten Prompts. |
|
|
| `src/page-layouts/` | Benutzerdefinierte Seitenlayouts für Datensatzansichten. |
|
|
| `src/__tests__/` | Integrationstests (Setup + Beispieltest). |
|
|
| `public/` | Statische Assets (Bilder, Schriftarten), die mit Ihrer App ausgeliefert werden. |
|
|
|
|
## Remotes verwalten
|
|
|
|
Ein **Remote** ist ein Twenty-Server, mit dem sich Ihre App verbindet. Während der Einrichtung erstellt das Scaffolding-Tool automatisch eines für Sie. Sie können jederzeit weitere Remotes hinzufügen oder zwischen ihnen wechseln.
|
|
|
|
```bash filename="Terminal"
|
|
# Add a new remote (opens a browser for OAuth login)
|
|
yarn twenty remote add
|
|
|
|
# Connect to a local Twenty server (auto-detects port 2020 or 3000)
|
|
yarn twenty remote add --local
|
|
|
|
# Add a remote non-interactively (useful for CI)
|
|
yarn twenty remote add --api-url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote
|
|
|
|
# List all configured remotes
|
|
yarn twenty remote list
|
|
|
|
# Switch the active remote
|
|
yarn twenty remote switch <name>
|
|
```
|
|
|
|
Ihre Anmeldedaten werden in `~/.twenty/config.json` gespeichert.
|
|
|
|
## Lokaler Entwicklungsserver (`yarn twenty server`)
|
|
|
|
Die CLI kann einen lokalen, in Docker laufenden Twenty-Server verwalten. Dies ist derselbe Server, der automatisch gestartet wird, wenn Sie mit `create-twenty-app` eine App aufsetzen, aber Sie können ihn auch manuell verwalten.
|
|
|
|
### Server starten
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server start
|
|
```
|
|
|
|
Dadurch wird das Docker-Image `twentycrm/twenty-app-dev:latest` heruntergeladen (falls nicht bereits vorhanden), ein Container namens `twenty-app-dev` erstellt und auf Port **2020** gestartet. Die CLI wartet, bis der Server seinen Health-Check bestanden hat, bevor sie zurückkehrt.
|
|
|
|
Es werden zwei Docker-Volumes erstellt, um Daten zwischen Neustarts beizubehalten:
|
|
|
|
* `twenty-app-dev-data` — PostgreSQL-Datenbank
|
|
* `twenty-app-dev-storage` — Dateispeicher
|
|
|
|
Wenn Port 2020 bereits verwendet wird, können Sie auf einem anderen Port starten:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server start --port 3030
|
|
```
|
|
|
|
Die CLI konfiguriert automatisch die internen Werte `NODE_PORT` und `SERVER_URL` des Containers passend zum gewählten Port, sodass Logikfunktionen, OAuth und alle anderen internen Netzwerkfunktionen korrekt arbeiten.
|
|
|
|
Nach dem Start wird der Server automatisch als `local`-Remote in Ihrer CLI-Konfiguration registriert.
|
|
|
|
### Serverstatus prüfen
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server status
|
|
```
|
|
|
|
Zeigt an, ob der Server läuft, seine URL und die Standard-Anmeldedaten (`tim@apple.dev` / `tim@apple.dev`).
|
|
|
|
### Serverprotokolle anzeigen
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server logs
|
|
```
|
|
|
|
Streamt die Containerprotokolle. Verwenden Sie `--lines`, um zu steuern, wie viele der letzten Zeilen angezeigt werden:
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server logs --lines 100
|
|
```
|
|
|
|
### Server stoppen
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server stop
|
|
```
|
|
|
|
Stoppt den Container. Ihre Daten bleiben in den Docker-Volumes erhalten — der nächste `start` macht dort weiter, wo Sie aufgehört haben.
|
|
|
|
### Server zurücksetzen
|
|
|
|
```bash filename="Terminal"
|
|
yarn twenty server reset
|
|
```
|
|
|
|
Entfernt den Container **und** löscht beide Docker-Volumes, wobei alle Daten gelöscht werden. Der nächste `start` erstellt eine frische Instanz.
|
|
|
|
<Note>
|
|
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.
|
|
</Note>
|
|
|
|
### Befehlsreferenz
|
|
|
|
| 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 |
|
|
|
|
## CI mit GitHub Actions
|
|
|
|
Das Scaffolding-Tool erzeugt einen einsatzbereiten GitHub-Actions-Workflow in `.github/workflows/ci.yml`. Er führt Ihre Integrationstests automatisch bei jedem Push auf `main` und bei Pull Requests aus.
|
|
|
|
Der Workflow:
|
|
|
|
1. Checkt Ihren Code aus
|
|
2. Startet einen temporären Twenty-Server mit der Aktion `twentyhq/twenty/.github/actions/spawn-twenty-docker-image`
|
|
3. Installiert Abhängigkeiten mit `yarn install --immutable`
|
|
4. Führt `yarn test` aus, wobei `TWENTY_API_URL` und `TWENTY_API_KEY` aus den Aktionsausgaben injiziert werden.
|
|
|
|
```yaml .github/workflows/ci.yml
|
|
name: CI
|
|
|
|
on:
|
|
push:
|
|
branches:
|
|
- main
|
|
pull_request: {}
|
|
|
|
env:
|
|
TWENTY_VERSION: latest
|
|
|
|
jobs:
|
|
test:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- name: Checkout
|
|
uses: actions/checkout@v4
|
|
|
|
- name: Spawn Twenty instance
|
|
id: twenty
|
|
uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main
|
|
with:
|
|
twenty-version: ${{ env.TWENTY_VERSION }}
|
|
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
|
|
- name: Enable Corepack
|
|
run: corepack enable
|
|
|
|
- name: Setup Node.js
|
|
uses: actions/setup-node@v4
|
|
with:
|
|
node-version-file: '.nvmrc'
|
|
cache: 'yarn'
|
|
|
|
- name: Install dependencies
|
|
run: yarn install --immutable
|
|
|
|
- name: Run integration tests
|
|
run: yarn test
|
|
env:
|
|
TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }}
|
|
TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }}
|
|
```
|
|
|
|
Sie müssen keine Secrets konfigurieren — die Aktion `spawn-twenty-docker-image` startet einen flüchtigen Twenty-Server direkt im Runner und gibt die Verbindungsdetails aus. Das Secret `GITHUB_TOKEN` wird automatisch von GitHub bereitgestellt.
|
|
|
|
Um eine bestimmte Twenty-Version statt `latest` festzulegen, ändern Sie die Umgebungsvariable `TWENTY_VERSION` oben im Workflow.
|
|
|
|
## 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:**
|
|
|
|
```bash filename="Terminal"
|
|
yarn add twenty-sdk twenty-client-sdk
|
|
```
|
|
|
|
**2. Fügen Sie Ihrer `package.json` ein `twenty`-Skript hinzu:**
|
|
|
|
```json filename="package.json"
|
|
{
|
|
"scripts": {
|
|
"twenty": "twenty"
|
|
}
|
|
}
|
|
```
|
|
|
|
Sie können jetzt `yarn twenty dev`, `yarn twenty help` und alle anderen Befehle ausführen.
|
|
|
|
<Note>
|
|
Installieren Sie `twenty-sdk` nicht global. Verwenden Sie es immer als lokale Projektabhängigkeit, damit jedes Projekt seine eigene Version festlegen kann.
|
|
</Note>
|
|
|
|
## 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](https://discord.com/channels/1130383047699738754/1130386664812982322) um Hilfe.
|