github-actions[bot]
2b3b2362db
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
102 lines
8.9 KiB
Plaintext
102 lines
8.9 KiB
Plaintext
---
|
||
title: Concepts
|
||
description: Fonctionnement des applications Twenty — modèle d’entité, sandboxing et cycle de vie de l’installation.
|
||
icon: sitemap
|
||
---
|
||
|
||
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
|
||
```
|
||
|
||
<Note>
|
||
**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.
|
||
</Note>
|
||
|
||
## Types d’entités
|
||
|
||
| Entité | Objectif | Documentation |
|
||
| --------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
||
| **Application** | Identité de l’application, rôle par défaut, variables | [Configuration de l’application](/l/fr/developers/extend/apps/config/application) |
|
||
| **Rôle** | Ensembles d’autorisations pour les objets et les champs | [Rôles et autorisations](/l/fr/developers/extend/apps/config/roles) |
|
||
| **Objet** | Types d’enregistrements personnalisés avec des champs | [Objets](/l/fr/developers/extend/apps/data/objects) |
|
||
| **Champ** | Ajouter des champs à des objets provenant d’autres applications | [Extension des objets](/l/fr/developers/extend/apps/data/extending-objects) |
|
||
| **Relation** | Liens bidirectionnels entre les objets | [Relations](/l/fr/developers/extend/apps/data/relations) |
|
||
| **Fonction logique** | TypeScript côté serveur avec des déclencheurs | [Fonctions logiques](/l/fr/developers/extend/apps/logic/logic-functions) |
|
||
| **Compétence** | Instructions réutilisables pour des agents d’IA | [Compétences et agents](/l/fr/developers/extend/apps/logic/skills-and-agents) |
|
||
| **Agent** | Assistants d’IA avec des prompts personnalisés | [Compétences et agents](/l/fr/developers/extend/apps/logic/skills-and-agents) |
|
||
| **Fournisseur de connexion** | Identifiants OAuth pour les API tierces | [Connexions](/l/fr/developers/extend/apps/logic/connections) |
|
||
| **Vue** | Vues de liste d’enregistrements préconfigurées | [Vues](/l/fr/developers/extend/apps/layout/views) |
|
||
| **Élément de menu de navigation** | Entrées personnalisées de la barre latérale | [Éléments du menu de navigation](/l/fr/developers/extend/apps/layout/navigation-menu-items) |
|
||
| **Mise en page** | Onglets et widgets sur la page de détails d’un enregistrement | [Mises en page](/l/fr/developers/extend/apps/layout/page-layouts) |
|
||
| **Composant frontal** | Interface React isolée en bac à sable dans Twenty | [Composants frontaux](/l/fr/developers/extend/apps/layout/front-components) |
|
||
| **Élément du menu de commande** | Actions rapides et entrées Cmd+K | [Éléments du menu de commande](/l/fr/developers/extend/apps/layout/command-menu-items) |
|
||
|
||
## 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] │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ 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** — fonctions optionnelles qui s’exécutent pendant l’installation. Voir [Install Hooks](/l/fr/developers/extend/apps/config/install-hooks) pour plus de détails.
|
||
|
||
## 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 et hooks d’installation.
|
||
</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>
|