Où les composants frontaux peuvent être utilisés
Les composants frontaux peuvent s’afficher à deux emplacements au sein de Twenty :- Panneau latéral — Les composants frontaux non-headless s’ouvrent dans le panneau latéral droit. Il s’agit du comportement par défaut lorsqu’un composant frontal est déclenché depuis le menu de commande.
- Widgets (tableaux de bord et pages d’enregistrement) — Les composants frontaux peuvent être intégrés comme widgets dans les mises en page. Lors de la configuration d’un tableau de bord ou d’une page d’enregistrement, les utilisateurs peuvent ajouter un widget de composant frontal.
- L’associer à un élément de menu de commande — l’enregistre dans le menu de commande (Cmd+K) et, éventuellement, comme action rapide épinglée.
- L’intégrer comme widget dans une mise en page — le place sur la page de détails d’un enregistrement ou sur un tableau de bord.
Exemple de base
La façon la plus rapide de voir un composant frontal en action est de l’associer à undefineCommandMenuItem, afin qu’il apparaisse comme bouton d’action rapide dans le coin supérieur droit de la page :
src/front-components/hello-world.tsx
src/command-menu-items/hello-world.command-menu-item.ts
yarn twenty dev (ou en exécutant une seule fois yarn twenty apply), l’action rapide apparaît dans le coin supérieur droit de la page :

Champs de configuration
| Champ | Obligatoire | Description |
|---|---|---|
universalIdentifier | Oui | ID unique et stable pour ce composant |
component | Oui | Une fonction de composant React |
name | Non | Nom d’affichage |
description | Non | Description de ce que fait le composant |
isHeadless | Non | Définir sur true si le composant n’a pas d’interface visible (voir ci-dessous) |
Placer un composant frontal sur une page
Au-delà des commandes, vous pouvez intégrer un composant frontal directement dans une page d’enregistrement en l’ajoutant comme widget dans une mise en page. Voir mises en page pour plus de détails.Headless vs non-headless
Les composants frontaux existent en deux modes de rendu contrôlés par l’optionisHeadless :
Non-headless (par défaut) — Le composant affiche une interface visible. Lorsqu’il est déclenché depuis le menu de commande, il s’ouvre dans le panneau latéral. Il s’agit du comportement par défaut lorsque isHeadless est false ou omis.
Headless (isHeadless: true) — Le composant se monte de façon invisible en arrière-plan. Il n’ouvre pas le panneau latéral. Les composants headless sont conçus pour des actions qui exécutent une logique puis se démontent — par exemple, lancer une tâche asynchrone, naviguer vers une page ou afficher une fenêtre modale de confirmation. Ils s’associent naturellement aux composants Command du SDK décrits ci-dessous.
src/front-components/sync-tracker.tsx
null, Twenty n’affiche pas de conteneur pour celui-ci — aucun espace vide n’apparaît dans la mise en page. Le composant a toujours accès à tous les hooks et à l’API de communication de l’hôte.
Composants Command du SDK
Le packagetwenty-sdk fournit quatre composants utilitaires Command conçus pour les composants frontaux headless. Chaque composant exécute une action au montage, gère les erreurs en affichant une notification snackbar et démonte automatiquement le composant frontal une fois terminé.
Importez-les depuis twenty-sdk/front-component :
Command— Exécute un callback asynchrone via la propexecute.CommandLink— Navigue vers un chemin d’application. Props :to,params,queryParams,options.CommandModal— Ouvre une fenêtre modale de confirmation. Si l’utilisateur confirme, exécute le callbackexecute. Props :title,subtitle,execute,confirmButtonText,confirmButtonAccent.CommandOpenSidePanelPage— Ouvre une page du panneau latéral. Les propriétés dépendent depage— par exemple,ViewRecordaccepterecordId+objectNameSingular, les autres pages acceptentpageTitle+pageIcon.
Command pour exécuter une action depuis le menu de commande :
src/front-components/run-action.tsx
src/command-menu-items/run-action.command-menu-item.ts
CommandModal pour demander une confirmation avant l’exécution :
src/front-components/delete-draft.tsx
Appel d’une fonction logique
Les composants front s’exécutent côté navigateur dans un Web Worker isolé (sandboxé) à l’intérieur d’un iframe à origine opaque, tandis que les fonctions logiques s’exécutent côté serveur. Il n’y a aucun appel intra-processus direct entre les deux — à la place, un composant front appelle une fonction logique via HTTP. Une fonction logique déclarée avechttpRouteTriggerSettings est accessible via HTTP à son chemin de route. Twenty injecte dans le worker l’URL de base à partir de laquelle vos fonctions sont servies sous la forme de TWENTY_FUNCTIONS_URL, ainsi que le TWENTY_APP_ACCESS_TOKEN qui authentifie l’appel. Il n’existe pas encore de client SDK dédié pour invoquer vos propres fonctions, donc appelez-les avec un simple fetch :
Sur Twenty Cloud, les fonctions logiques déclenchées par HTTP sont servies sur un domaine dédié par espace de travail à l’adresseUn composant front sans interface (headless) peut effectuer l’appel au montage via le composanthttps://\<your-workspace-subdomain>.withtwenty.com\<path>— c’est exactement ce à quoiTWENTY_FUNCTIONS_URLcorrespond. Pour les appelants externes, copiez l’URL exacte à partir des paramètres HTTP trigger de la fonction ou de l’onglet Settings de l’application.
Command, puis se démonter automatiquement :
src/front-components/sync-prs.tsx
TWENTY_FUNCTIONS_URL correspond au httpRouteTriggerSettings.path de la fonction logique. Conservez isAuthRequired: true ; le TWENTY_APP_ACCESS_TOKEN que Twenty génère pour votre composant authentifie la requête :
src/logic-functions/fetch-prs.logic-function.ts
TWENTY_FUNCTIONS_URL et TWENTY_APP_ACCESS_TOKEN sont injectés automatiquement — voir Variables d’application. Comme les variables d’application secrètes ne sont jamais exposées aux composants front, conservez les clés d’API et les autres éléments sensibles dans la fonction logique, et non dans le composant front.Appeler l’API REST de Twenty
Pour lire ou écrire des enregistrements Twenty depuis un composant frontal, utilisezRestApiClient depuis twenty-client-sdk/rest. Il appartient à la même famille de clients que CoreApiClient et MetadataApiClient, mais cible l’API REST de Twenty (/rest/...) plutôt que l’API GraphQL, en lisant son URL de base depuis TWENTY_API_URL.
| Méthode | Description |
|---|---|
get(path, options?) | Envoie une requête GET |
post(path, body?, options?) | Envoie une requête POST |
put(path, body?, options?) | Envoie une requête PUT |
patch(path, body?, options?) | Envoie une requête PATCH |
delete(path, options?) | Envoie une requête DELETE |
request(method, path, options?) | Requête générique avec n’importe quelle méthode HTTP |
options accepte headers, query (un enregistrement de paramètres de chaîne de requête ; les valeurs nullish sont ignorées), et un AbortSignal via signal. Un objet body qui n’est pas de type FormData est automatiquement sérialisé en JSON. Sur un 401, le client actualise une fois le jeton d’accès via l’hôte puis retente la requête.
Par défaut, l’URL de base et le jeton sont résolus à partir de l’environnement. Passez des valeurs de remplacement (overrides) au constructeur lorsque nécessaire — par exemple dans les tests :
RestApiClientError exposant status, statusText, url et le body analysé :
Accéder au contexte d’exécution
Dans votre composant, utilisez les hooks du SDK pour accéder à l’utilisateur actuel, à l’enregistrement et à l’instance du composant :src/front-components/record-info.tsx
| Hook | Renvoie | Description |
|---|---|---|
useUserId() | string ou null | L’ID de l’utilisateur actuel |
useSelectedRecordIds() | string[] | Tous les ID des enregistrements sélectionnés (tableau vide si aucun n’est sélectionné) |
useRecordId() | string ou null | Obsolète. Utilisez useSelectedRecordIds() à la place |
useFrontComponentId() | string | L’ID de cette instance de composant |
useColorScheme() | 'light' ou 'dark' | Schéma de couleur actif de l’interface hôte (System est déjà résolu) |
useFrontComponentExecutionContext(selector) | variable | Accédez au contexte d’exécution complet avec une fonction sélecteur |
Variables d’application
Les variables d’application définies dansdefineApplication() avec isSecret: false sont disponibles dans les composants front via l’utilitaire getApplicationVariable :
src/front-components/greeting.tsx
getApplicationVariable renvoie toujours une chaîne (ou undefined), quel que soit le type déclaré de la variable. La chaîne est sérialisée de manière cohérente selon le type (booléens sous la forme "true" / "false", nombres sous forme de chaînes décimales, tableaux / objets en JSON), dans le même format utilisé pour la fonction logique process.env — analysez-la vous-même (Number(...), JSON.parse(...), === 'true'). Voir Types de variables.
Les variables système suivantes sont toujours disponibles via process.env :
| Variable | Description |
|---|---|
TWENTY_FUNCTIONS_URL | URL de base à partir de laquelle les fonctions de logique HTTP de votre application sont servies |
TWENTY_API_URL | URL de base de l’API principale de Twenty |
TWENTY_APP_ACCESS_TOKEN | Jeton de courte durée limité au rôle de votre application |
API de communication de l’hôte
Les composants frontaux peuvent déclencher la navigation, des modales et des notifications en utilisant des fonctions detwenty-sdk :
| Fonction | Description |
|---|---|
navigate(to, params?, queryParams?, options?) | Naviguer vers une page de l’application |
openSidePanelPage(params) | Ouvrir un panneau latéral |
closeSidePanel() | Fermer le panneau latéral |
openCommandConfirmationModal(params) | Afficher une boîte de dialogue de confirmation |
enqueueSnackbar(params) | Afficher une notification toast |
unmountFrontComponent() | Démonter le composant |
updateProgress(progress) | Mettre à jour un indicateur de progression |
src/front-components/archive-record.tsx
Travailler avec plusieurs enregistrements
UtilisezuseSelectedRecordIds() pour gérer plusieurs enregistrements sélectionnés. C’est utile pour les opérations groupées :
src/front-components/bulk-export.tsx
src/command-menu-items/bulk-export.command-menu-item.ts
Ressources publiques
Les composants frontaux peuvent accéder aux fichiers du répertoirepublic/ de l’application à l’aide de getPublicAssetUrl :
Stylisation
Les composants frontaux prennent en charge plusieurs approches de stylisation. Vous pouvez utiliser :- Styles en ligne —
style={{ color: 'red' }} - Composants d’interface utilisateur Twenty — la bibliothèque de composants propre à Twenty ; voir Utilisation des composants d’interface utilisateur Twenty ci-dessous
- Emotion — CSS-in-JS avec
@emotion/react - Styled-components — modèles
styled.div - Tailwind CSS — classes utilitaires
- Toute bibliothèque CSS-in-JS compatible avec React
Utilisation des composants d’interface utilisateur Twenty
Twenty fournit sa bibliothèque de composants sous forme de packagetwenty-ui. Les composants frontaux peuvent l’utiliser pour les boutons, tags, pastilles de statut, chips, avatars, icônes, typographie et jetons de thème qui s’adaptent automatiquement aux thèmes clair et sombre de l’espace de travail.
Installation
Ajoutez le package à votre application, épinglé à la version livrée avec votre instance Twenty :twenty-ui est intégré à votre composant front au moment du build, il n’a donc besoin d’être qu’une dépendance de votre application — il n’y a rien à configurer à l’exécution.
Importation de composants
Importez depuis le sous-chemin correspondant plutôt que depuis la racine du package, afin que seuls les composants que vous utilisez se retrouvent dans votre bundle :| Sous-chemin | Ce qu’il exporte |
|---|---|
twenty-ui/input | Button et champs de formulaire |
twenty-ui/data-display | Tag, Status, Chip, Avatar, et plus encore |
twenty-ui/feedback | Callout, Banner, Info, et plus encore |
twenty-ui/typography | H1Title, H2Title, H3Title, Label, et plus encore |
twenty-ui/icon | Composants Icon* (par exemple IconCheck) |
twenty-ui/theme-constants | ThemeProvider, themeCssVariables |
Icônes
Importez des icônes individuelles depuistwenty-ui/icon :
IconsProvider, useIcons et iconsState — ils intègrent l’ensemble complet d’icônes Tabler (plusieurs Mo).
Thématisation et jetons de thème
Les composants Twenty UI correspondent automatiquement au thème clair et sombre de l’espace de travail — le moteur de rendu applique le jeu de couleurs actif sur l’hôte, et les composants résolvent leurs couleurs par rapport à celui-ci. Pour utiliser les mêmes jetons de design dans vos propres styles inline, appelez le hookuseTheme(). Il renvoie les jetons de thème de Twenty (espacement, couleurs, rayons, polices) connectés au thème actif, sans qu’aucune configuration de ThemeProvider ne soit nécessaire dans votre composant :
useTheme() est un hook, vous lisez les jetons à l’intérieur du corps du composant, de sorte que les valeurs reflètent toujours le thème en cours. La même table de jetons est également exportée en tant que constante themeCssVariables, mais privilégiez useTheme() dans les composants front — une constante au niveau du module qui déréférence themeCssVariables peut être indéfinie pendant l’extraction du manifeste de l’application.
Pour bifurquer explicitement selon le jeu de couleurs actif, lisez-le avec useColorScheme() depuis twenty-sdk/front-component, qui renvoie 'light' ou 'dark'.