github-actions[bot]
2b3b2362db
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
177 lines
12 KiB
Plaintext
177 lines
12 KiB
Plaintext
---
|
||
title: Démarrage rapide
|
||
icon: rocket
|
||
description: Créez votre première application Twenty en quelques minutes.
|
||
---
|
||
|
||
## Prérequis
|
||
|
||
* **Node.js 24+** — [Télécharger](https://nodejs.org/)
|
||
* **Yarn 4** — fourni avec Node.js via Corepack. Activez-le : `corepack enable`
|
||
* **Docker** — [Télécharger](https://www.docker.com/products/docker-desktop/). Nécessaire pour exécuter un serveur Twenty local. Ignorez si vous avez déjà Twenty en cours d’exécution ailleurs.
|
||
|
||
La création d’une application Twenty comporte trois phases. Le générateur les regroupe en une seule commande pour le parcours idéal, mais chaque phase est un concept distinct — en cas d’échec, savoir dans quelle phase vous vous trouvez indique ce qu’il faut corriger.
|
||
|
||
| 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 server` | 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 :
|
||
|
||
```bash filename="Terminal"
|
||
npx create-twenty-app@latest my-twenty-app
|
||
```
|
||
|
||
On vous demandera un nom et une description — appuyez sur **Entrée** pour utiliser les valeurs par défaut. 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, un workflow CI 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 propose d’en démarrer un pour vous :
|
||
|
||
> **Souhaitez-vous configurer une instance locale de Twenty ?**
|
||
|
||
* **Oui (recommandé)** — récupère l’image Docker `twentycrm/twenty-app-dev` et la démarre sur le port `2020`. Assurez-vous d’abord que Docker est en cours d’exécution.
|
||
* **Non** — choisissez cette option si vous avez déjà un serveur Twenty auquel vous souhaitez vous connecter. Vous pourrez le connecter plus tard avec `yarn twenty remote:add`.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Faut-il démarrer l’instance locale ?" />
|
||
</div>
|
||
|
||
Une fois le serveur démarré, un navigateur s’ouvre pour la connexion. Utilisez le compte de démonstration prérempli :
|
||
|
||
* **E-mail :** `tim@apple.dev`
|
||
* **Mot de passe :** `tim@apple.dev`
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/login.png" alt="Écran de connexion Twenty" />
|
||
</div>
|
||
|
||
Cliquez sur **Authorize** sur l’écran suivant — cela donne à la CLI l’accès à votre espace de travail.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Écran d’autorisation de la CLI Twenty" />
|
||
</div>
|
||
|
||
Votre terminal confirmera que tout est configuré.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/scaffolded.png" alt="Application initialisée avec succès" />
|
||
</div>
|
||
|
||
**Après cette phase :** vous disposez d’un serveur Twenty en cours d’exécution sur [http://localhost:2020](http://localhost:2020) avec votre CLI autorisée à s’y synchroniser.
|
||
|
||
<Note>
|
||
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.
|
||
</Note>
|
||
|
||
---
|
||
|
||
## Phase 3 — Synchroniser vos modifications
|
||
|
||
C’est la boucle interne dans laquelle vous passerez la plupart de votre temps.
|
||
|
||
```bash filename="Terminal"
|
||
cd my-twenty-app
|
||
yarn twenty dev
|
||
```
|
||
|
||
Cela surveille `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`.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/dev.png" alt="Sortie du terminal en mode dev" />
|
||
</div>
|
||
|
||
Ouvrez [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Vous devriez voir votre application sous **Your Apps**.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="La liste Your Apps affichant My twenty app" />
|
||
</div>
|
||
|
||
Cliquez sur **My twenty app** pour voir son **application registration** — un enregistrement au niveau du serveur décrivant votre application (nom, identifiant, informations d’identification OAuth, source). Un même enregistrement peut être installé dans plusieurs espaces de travail sur le même serveur.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Détails de l’enregistrement d’application" />
|
||
</div>
|
||
|
||
Cliquez sur **View installed app** pour voir l’installation dans l’espace de travail. L’onglet **About** affiche la version et les options de gestion.
|
||
|
||
<div style={{textAlign: 'center'}}>
|
||
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="Application installée" />
|
||
</div>
|
||
|
||
**Après cette phase :** vous disposez d’une boucle de développement en direct. Modifiez n’importe quel fichier dans `src/` et il apparaît dans l’interface utilisateur.
|
||
|
||
### Synchronisation ponctuelle pour la CI et les scripts
|
||
|
||
Passez `--once` pour exécuter une seule opération de build + synchronisation puis quitter — même pipeline, pas de watcher :
|
||
|
||
```bash filename="Terminal"
|
||
yarn twenty dev --once
|
||
```
|
||
|
||
| 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 dev --once` | Une seule opération de build + synchronisation, se termine avec le code `0` en cas de réussite et `1` en cas d’échec. | CI, hooks de pré-commit, agents IA et flux de travail scriptés. |
|
||
| `yarn twenty dev --once --dry-run` | Construit et affiche les modifications de métadonnées **sans les appliquer**. | Inspection de ce qu’une synchronisation changerait avant de s’y engager. |
|
||
|
||
Les deux modes nécessitent un serveur distant authentifié. Voir [synchronisation et récupération](/l/fr/developers/extend/apps/operations/sync-and-recovery#previewing-changes-dry-run) pour plus d’informations sur `--dry-run`.
|
||
|
||
### Options du mode de développement
|
||
|
||
| Option | Description |
|
||
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
|
||
| `--once` | Construire et synchroniser une fois, puis quitter. |
|
||
| `--dry-run` | Avec `--once`, prévisualisez les modifications de métadonnées sans les appliquer. N’écrit rien. |
|
||
| `--debounceMs \<ms>` | Définir le délai de temporisation des modifications de fichiers en millisecondes (valeur par défaut : `2000`). |
|
||
| `--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 seul `export 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 |
|
||
|
||
Référence complète : [Concepts](/l/fr/developers/extend/apps/getting-started/concepts).
|
||
|
||
## Prochaines étapes
|
||
|
||
<CardGroup cols={2}>
|
||
<Card title="Configuration" icon="screwdriver-wrench" href="/l/fr/developers/extend/apps/config/overview">
|
||
Identité de l’application, rôle par défaut, hooks d’installation, ressources publiques.
|
||
</Card>
|
||
<Card title="Données" icon="database" href="/l/fr/developers/extend/apps/data/overview">
|
||
Objets, champs et relations bidirectionnelles.
|
||
</Card>
|
||
<Card title="Logique" icon="bolt" href="/l/fr/developers/extend/apps/logic/overview">
|
||
Fonctions logiques, compétences, agents et connexions OAuth.
|
||
</Card>
|
||
<Card title="Disposition" icon="table-columns" href="/l/fr/developers/extend/apps/layout/overview">
|
||
Vues, navigation, mises en page, composants front-end.
|
||
</Card>
|
||
<Card title="Opérations" icon="rocket" href="/l/fr/developers/extend/apps/operations/overview">
|
||
CLI, tests, dépôts distants, CI et publication de votre application.
|
||
</Card>
|
||
</CardGroup>
|