Concepts

Les applications Twenty sont des packages TypeScript qui étendent votre espace de travail avec des objets personnalisés, de la logique, des composants d’interface utilisateur et des capacités d’IA. Elles s’exécutent sur la plateforme Twenty avec une isolation complète en bac à sable et des contrôles d’autorisations.

Fonctionnement des applications

Une application est un ensemble d’entités déclarées à l’aide des fonctions defineEntity() du package twenty-sdk. Le SDK détecte ces déclarations via une analyse de l’AST au moment de la compilation et produit un manifeste — une description complète de ce que votre application ajoute à un espace de travail. Ces fonctions valident votre configuration au moment de la compilation et offrent l’autocomplétion dans l’IDE et une sécurité de typage.

your-app/
├── src/
│   ├── application-config.ts    ← defineApplication (required, one per app)
│   ├── roles/                   ← defineRole
│   ├── objects/                 ← defineObject
│   ├── fields/                  ← defineField
│   ├── logic-functions/         ← defineLogicFunction
│   ├── front-components/        ← defineFrontComponent
│   ├── skills/                  ← defineSkill
│   ├── agents/                  ← defineAgent
│   ├── views/                   ← defineView
│   ├── navigation-menu-items/   ← defineNavigationMenuItem
│   └── page-layouts/            ← definePageLayout
├── public/                      ← Static assets (images, icons)
└── package.json

L’organisation des fichiers vous revient. La détection des entités est basée sur l’AST — le SDK trouve les appels à export default defineEntity(...) quel que soit l’emplacement du fichier. La structure de dossiers ci-dessus est une convention, pas une obligation.

Types d’entités

Entité	Objectif	Documentation
Application	Identité de l’application, rôle par défaut, variables	Configuration de l’application
Rôle	Ensembles d’autorisations pour les objets et les champs	Rôles et autorisations
Objet	Types d’enregistrements personnalisés avec des champs	Objets
Champ	Ajouter des champs à des objets provenant d’autres applications	Extension des objets
Relation	Liens bidirectionnels entre les objets	Relations
Fonction logique	TypeScript côté serveur avec des déclencheurs	Fonctions logiques
Compétence	Instructions réutilisables pour des agents d’IA	Compétences et agents
Agent	Assistants d’IA avec des prompts personnalisés	Compétences et agents
Fournisseur de connexion	Identifiants OAuth pour les API tierces	Connexions
Vue	Vues de liste d’enregistrements préconfigurées	Vues
Élément de menu de navigation	Entrées personnalisées de la barre latérale	Éléments du menu de navigation
Mise en page	Onglets et widgets sur la page de détails d’un enregistrement	Mises en page
Composant frontal	Interface React isolée en bac à sable dans Twenty	Composants frontaux
Élément du menu de commande	Actions rapides et entrées Cmd+K	Éléments du menu de commande

Exécution en bac à sable

Les fonctions logiques s’exécutent dans des processus Node.js isolés sur le serveur. Elles n’accèdent aux données qu’au moyen du client d’API typé, limité par les autorisations du rôle de l’application.
Les composants frontaux s’exécutent dans des Web Workers en utilisant Remote DOM — isolés en bac à sable de la page principale mais rendant des éléments DOM natifs (pas d’iframes). Ils communiquent avec Twenty via une API hôte de passage de messages.
Les autorisations sont appliquées au niveau de l’API. Le jeton d’exécution (TWENTY_APP_ACCESS_TOKEN) est dérivé du rôle défini dans defineApplication().

Cycle de vie de l’application

┌─────────────────────────────────────────────────────────┐
│ Development                                             │
│   npx create-twenty-app → yarn twenty dev (live sync)   │
├─────────────────────────────────────────────────────────┤
│ Build & Deploy                                          │
│   yarn twenty dev:build → yarn twenty app:publish        │
├─────────────────────────────────────────────────────────┤
│ Install flow                                            │
│   upload → [pre-install] → metadata migration →         │
│   generate SDK → [post-install] → … → [uninstall]       │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘

yarn twenty dev — surveille vos fichiers source et synchronise en direct les modifications avec un serveur Twenty connecté. Le client d’API typé est régénéré automatiquement lorsque le schéma change.
yarn twenty dev:build — compile TypeScript, regroupe les fonctions logiques et les composants frontaux avec esbuild, et produit un manifeste.
Hooks pré/post-install et de désinstallation — fonctions optionnelles qui s’exécutent pendant l’installation ou juste avant la désinstallation. Voir Install Hooks pour plus de détails.

Prochaines étapes

Configuration

Identité de l’application, rôle par défaut et hooks d’installation et de désinstallation.

Données

Objets, champs et relations bidirectionnelles.

Logique

Fonctions logiques, compétences, agents et connexions OAuth.

Disposition

Vues, navigation, mises en page, composants front-end.

Opérations

CLI, tests, dépôts distants, CI et publication de votre application.

Vue d'ensemble

Applications

API

Auto-hébergement

Contribuer

Fonctionnement des applications

Types d’entités

Exécution en bac à sable

Cycle de vie de l’application

Prochaines étapes

Configuration

Données

Logique

Disposition

Opérations

​Fonctionnement des applications

​Types d’entités

​Exécution en bac à sable

​Cycle de vie de l’application

​Prochaines étapes

Configuration

Données

Logique

Disposition

Opérations

Fonctionnement des applications

Types d’entités

Exécution en bac à sable

Cycle de vie de l’application

Prochaines étapes