Erste Schritte

• Benutzerdefinierte Objekte und Felder als Code definieren (verwaltetes Datenmodell)
• Erstellen Sie Logikfunktionen mit benutzerdefinierten Triggern (HTTP-Routen, cron, Datenbankereignisse)
• Fähigkeiten für KI-Agenten definieren
• Erstellen Sie Frontend-Komponenten, die in der Twenty-UI gerendert werden
• Dieselbe App in mehreren Workspaces bereitstellen

​

Voraussetzungen

• Node.js 24+ und Yarn 4
• Ein Twenty-Workspace und ein API-Schlüssel (unter https://app.twenty.com/settings/api-webhooks erstellen)

​

Erste Schritte

# Scaffold a new app (includes all examples by default)
npx create-twenty-app@latest my-twenty-app
cd my-twenty-app

# Start dev mode: automatically syncs local changes to your workspace
yarn twenty app:dev

# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill)
npx create-twenty-app@latest my-app

# Minimal: only core files (application-config.ts and default-role.ts)
npx create-twenty-app@latest my-app --minimal

# Add a new entity to your application (guided)
yarn twenty entity:add

# Watch your application's function logs
yarn twenty function:logs

# Execute a function by name
yarn twenty function:execute -n my-function -p '{"name": "test"}'

# Execute the pre-install function
yarn twenty function:execute --preInstall

# Execute the post-install function
yarn twenty function:execute --postInstall

# Uninstall the application from the current workspace
yarn twenty app:uninstall

# Display commands' help
yarn twenty help

​

Projektstruktur (vom Scaffolder erzeugt)

• Kopiert eine minimale Basisanwendung nach my-twenty-app/
• Fügt eine lokale twenty-sdk-Abhängigkeit und die Yarn-4-Konfiguration hinzu
• Erstellt Konfigurationsdateien und Skripte, die an die twenty-CLI angebunden sind
• Erzeugt Kerndateien (Anwendungskonfiguration, Standardrolle für Logikfunktionen, Pre-Installations- und Post-Installationsfunktionen) sowie Beispieldateien entsprechend dem Scaffolding-Modus

my-twenty-app/
  package.json
  yarn.lock
  .gitignore
  .nvmrc
  .yarnrc.yml
  .yarn/
    install-state.gz
  .oxlintrc.json
  tsconfig.json
  README.md
  public/                           # Public assets folder (images, fonts, etc.)
  src/
  ├── application-config.ts           # Required - main application configuration
  ├── 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
  │   ├── pre-install.ts                # Pre-install logic function
  │   └── post-install.ts               # Post-install logic function
  ├── front-components/
  │   └── hello-world.tsx               # Example 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

• package.json: Deklariert den App-Namen, die Version und die Engines (Node 24+, Yarn 4) und fügt twenty-sdk sowie ein twenty-Skript hinzu, das an die lokale twenty-CLI delegiert. Führen Sie yarn twenty help aus, um alle verfügbaren Befehle aufzulisten.
• .gitignore: Ignoriert übliche Artefakte wie node_modules, .yarn, generated/ (typisierter Client), dist/, build/, Coverage-Ordner, Logdateien und .env*-Dateien.
• yarn.lock, .yarnrc.yml, .yarn/: Fixieren und konfigurieren die vom Projekt verwendete Yarn-4-Toolchain.
• .nvmrc: Legt die vom Projekt erwartete Node.js-Version fest.
• .oxlintrc.json und tsconfig.json: Stellen Linting und TypeScript-Konfiguration für die TypeScript-Quellen Ihrer App bereit.
• README.md: Ein kurzes README im App-Root mit grundlegenden Anweisungen.
• public/: Ein Ordner zum Speichern öffentlicher Assets (Bilder, Schriftarten, statische Dateien), die zusammen mit Ihrer Anwendung bereitgestellt werden. Hier abgelegte Dateien werden während der Synchronisierung hochgeladen und sind zur Laufzeit zugänglich.
• src/: Der Hauptort, an dem Sie Ihre Anwendung als Code definieren

​

Entitätserkennung

// This file can be named anything and placed anywhere in src/
import { defineObject, FieldType } from 'twenty-sdk';

export default defineObject({
  universalIdentifier: '...',
  nameSingular: 'postCard',
  // ... rest of config
});

• yarn twenty app:dev generiert automatisch zwei typisierte API-Clients in node_modules/twenty-sdk/generated: CoreApiClient (für Arbeitsbereichsdaten über /graphql) und MetadataApiClient (für Arbeitsbereichskonfiguration und Datei-Uploads über /metadata).
• yarn twenty entity:add fügt unter src/ Entitätsdefinitionsdateien für Ihre benutzerdefinierten Objekte, Funktionen, Frontend-Komponenten, Rollen, Skills und mehr hinzu.

​

Authentifizierung

• API-URL (standardmäßig http://localhost:3000 oder Ihr aktuelles Workspace-Profil)
• API-Schlüssel

​

Arbeitsbereiche verwalten

# Login interactively (recommended)
yarn twenty auth:login

# Login to a specific workspace profile
yarn twenty auth:login --workspace my-custom-workspace

# List all configured workspaces
yarn twenty auth:list

# Switch the default workspace (interactive)
yarn twenty auth:switch

# Switch to a specific workspace
yarn twenty auth:switch production

# Check current authentication status
yarn twenty auth:status

​

Manuelle Einrichtung (ohne Scaffolder)

yarn add -D twenty-sdk

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

​

Fehlerbehebung

• Authentifizierungsfehler: Führen Sie yarn twenty auth:login aus und stellen Sie sicher, dass Ihr API-Schlüssel die erforderlichen Berechtigungen hat.
• Verbindung zum Server nicht möglich: Überprüfen Sie die API-URL und dass der Twenty-Server erreichbar ist.
• Typen oder Client fehlen/veraltet: Starten Sie yarn twenty app:dev neu — der typisierte Client wird automatisch generiert.
• Dev-Modus synchronisiert nicht: Stellen Sie sicher, dass yarn twenty app:dev läuft und dass Änderungen von Ihrer Umgebung nicht ignoriert werden.