github-actions[bot]
0b8421a45a
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
256 lines
13 KiB
Plaintext
256 lines
13 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>
|
|
|
|
## 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](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.
|
|
|
|
## Create your first app
|
|
|
|
### Scaffold your app
|
|
|
|
Ö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.
|
|
|
|
### Set up a local Twenty instance
|
|
|
|
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>
|
|
|
|
### Sign in to your workspace
|
|
|
|
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>
|
|
|
|
### Authorize the app
|
|
|
|
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>
|
|
|
|
### Start developing
|
|
|
|
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>
|
|
|
|
### See your app in Twenty
|
|
|
|
Ö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.
|
|
|
|
---
|
|
|
|
## Was Sie erstellen können
|
|
|
|
Apps are composed of **entities** — each defined as a TypeScript file with a single `export default`:
|
|
|
|
| Entity | What it does |
|
|
| ------------------------ | --------------------------------------------------------------------------------------------- |
|
|
| **Objects & Fields** | Define custom data models (like Post Card, Invoice) with typed fields |
|
|
| **Logikfunktionen** | Server-side TypeScript functions triggered by HTTP routes, cron schedules, or database events |
|
|
| **Frontend-Komponenten** | React components that render inside Twenty's UI (side panel, widgets, command menu) |
|
|
| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |
|
|
| **Views & Navigation** | Pre-configured list views and sidebar menu items for your objects |
|
|
| **Seitenlayouts** | Custom record detail pages with tabs and widgets |
|
|
|
|
Head over to [Building Apps](/l/de/developers/extend/apps/building) for a detailed guide on each entity type.
|
|
|
|
---
|
|
|
|
## Projektstruktur
|
|
|
|
The scaffolder generates the following file structure:
|
|
|
|
```text filename="my-twenty-app/"
|
|
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
|
|
```
|
|
|
|
### Starting from an example
|
|
|
|
To start from a more complete example with custom objects, fields, logic functions, front components, and more, use the `--example` flag:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app --example postcard
|
|
```
|
|
|
|
Examples are sourced from the [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) directory on GitHub. You can also scaffold individual entities into an existing project with `yarn twenty add` (see [Building Apps](/l/de/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)).
|
|
|
|
### 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` | Default role that controls what your logic functions can access. |
|
|
| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and app metadata (display name, description). |
|
|
| `src/__tests__/` | Integrationstests (Setup + Beispieltest). |
|
|
| `public/` | Statische Assets (Bilder, Schriftarten), die mit Ihrer App ausgeliefert werden. |
|
|
|
|
## Local development server
|
|
|
|
The scaffolder already started a local Twenty server for you. To manage it later, use `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 |
|
|
|
|
Data is persisted across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything and start fresh.
|
|
|
|
<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>
|
|
|
|
## 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.
|