Prérequis
- Node.js 24.5+ — Télécharger
- Yarn 4 — fourni avec Node.js via Corepack. Activez-le :
corepack enable - Docker — Télécharger. Nécessaire pour exécuter un serveur Twenty local. Ignorez si vous avez déjà Twenty en cours d’exécution ailleurs.
| Phase | Ce que vous faites | Outil | Résultat |
|---|---|---|---|
| 1. Génération | Générer le code source de l’application | npx create-twenty-app | Un projet TypeScript sur le disque |
| 2. Exécuter un serveur | Démarrer un serveur Twenty vers lequel se synchroniser | Docker + yarn twenty docker:start | Une instance Twenty en cours d’exécution |
| 3. Synchroniser | Synchroniser en direct votre code avec le serveur | yarn twenty dev | Vos modifications apparaissent dans l’interface utilisateur |
Phase 1 — Générez le squelette de votre projet
Créez une nouvelle application à partir du modèle :--display-name et --description pour personnaliser les métadonnées générées (vous pouvez également les modifier plus tard dans src/constants/universal-identifiers.ts). Cela génère un projet TypeScript dans my-twenty-app/ avec un fichier de démarrage application-config.ts, un rôle par défaut, des workflows CI/CD et un test d’intégration.
Après cette phase : vous disposez du code source d’une application sur votre machine. Elle ne s’exécute pas encore — c’est la phase 2.
Phase 2 — Exécuter un serveur Twenty local
Votre application a besoin d’un serveur Twenty vers lequel se synchroniser. Le serveur est une instance Twenty complète — interface utilisateur, API GraphQL, PostgreSQL — exécutée localement dans Docker. Votre code local envoie ses définitions à ce serveur, qui les fait apparaître dans l’interface utilisateur. Le générateur de projet en crée un pour vous : avec Docker en cours d’exécution, il récupère l’imagetwentycrm/twenty-app-dev, la démarre sur le port 2020, et authentifie le CLI auprès de l’espace de travail de démonstration prérempli (tim@apple.dev) — aucune connexion requise.
Pour vous connecter à un serveur Twenty existant à la place, passez --url \<your-server-url>. Les serveurs distants s’authentifient avec OAuth : un navigateur s’ouvre pour que vous puissiez vous connecter et cliquer sur Authorize, ce qui donne au CLI l’accès à votre espace de travail. (Vous pouvez aussi choisir OAuth en local avec --authentication-method oauth — connectez-vous avec tim@apple.dev / tim@apple.dev.)
Si Docker n’est pas installé ou en cours d’exécution, le générateur vous indiquera la bonne commande de démarrage pour votre système d’exploitation. Une fois Docker lancé, vous pouvez reprendre avec
yarn twenty docker:start — pas besoin de régénérer le squelette.Phase 3 — Synchroniser vos modifications
C’est la boucle interne dans laquelle vous passerez la plupart de votre temps.src/, reconstruit à chaque modification et synchronise le résultat avec le serveur. Modifiez un fichier, enregistrez, et en quelques secondes le serveur reflète la modification. Vous verrez un panneau d’état en direct dans votre terminal.
Pour une sortie plus détaillée (journaux de build, requêtes de synchronisation, traces d’erreurs), ajoutez --verbose.
src/ et il apparaît dans l’interface utilisateur.
Synchronisation ponctuelle pour la CI et les scripts
Utilisezplan et apply pour exécuter une fois le même pipeline, sans surveillance :
| Commande | Comportement | Quand l’utiliser : |
|---|---|---|
yarn twenty dev | Surveille et resynchronise à chaque modification. Reste en cours d’exécution jusqu’à ce que vous l’arrêtiez. | Développement local interactif. |
yarn twenty apply | Une seule opération de build + synchronisation, se termine avec le code 0 en cas de réussite et 1 en cas d’échec. Demande une confirmation pour les modifications destructrices (passez --force pour l’ignorer). | CI, hooks de pré-commit, agents IA et flux de travail scriptés. |
yarn twenty plan | Construit et affiche les modifications de métadonnées sans les appliquer. | Inspection de ce qu’une synchronisation changerait avant de s’y engager. |
plan.
yarn twenty dev --once et yarn twenty dev --once --dry-run sont des alias obsolètes pour yarn twenty apply et yarn twenty plan.Options du mode de développement
| Option | Description |
|---|---|
--force | Applique les modifications destructrices (suppressions) sans confirmation. |
--debounceMs \<ms> | Définir le délai de temporisation des modifications de fichiers en millisecondes (valeur par défaut : 1000). |
--verbose / --debug | Afficher des journaux de build détaillés, les requêtes de synchronisation et les traces d’erreur. |
Ce que vous pouvez créer
Les applications sont composées d’entités — chacune définie comme un fichier TypeScript avec un seulexport default :
| Entité | Ce que cela fait |
|---|---|
| Objets et champs | Modèles de données personnalisés (carte postale, facture, etc.) avec des champs typés |
| Fonctions logiques | Fonctions TypeScript côté serveur déclenchées par des routes HTTP, des tâches cron ou des événements de base de données |
| Composants d’interface utilisateur (UI) | Composants React qui s’affichent dans l’interface de Twenty (panneau latéral, widgets, menu de commandes) |
| Compétences et agents | Fonctionnalités d’IA — instructions réutilisables et assistants autonomes |
| Vues et navigation | Vues de liste préconfigurées et éléments de menu de la barre latérale |
| Mises en page | Pages de détail d’enregistrement personnalisées avec des onglets et des widgets |
Prochaines étapes
Configuration
Identité de l’application, rôle par défaut, hooks d’installation, ressources publiques.
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.