> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Publication
> Distribuez votre application Twenty sur la marketplace ou déployez-la en interne.
## Vue d'ensemble
Une fois que votre application est [créée et testée en local](/l/fr/developers/extend/apps/getting-started/concepts), vous avez deux options pour sa distribution :
* **Déployer une archive tar** — téléversez votre application directement sur un serveur Twenty spécifique pour un usage interne ou privé.
* **Publier sur npm** — répertoriez votre application dans la marketplace Twenty pour que tout espace de travail puisse la découvrir et l'installer.
Les deux parcours commencent à la même étape de **build**.
## Compilation de votre application
Exécutez la commande `build` pour compiler votre application et générer un `manifest.json` prêt pour la distribution :
```bash filename="Terminal" theme={null}
yarn twenty dev:build
```
Cela compile les sources TypeScript, transpile les fonctions de logique et les composants front-end, et écrit le tout dans `.twenty/output/`. Ajoutez `--tarball` pour produire également un paquet `.tgz` pour la distribution manuelle ou la commande `publish`.
## Déploiement sur un serveur (archive tar)
Pour les applications que vous ne souhaitez pas rendre publiques — outils propriétaires, intégrations réservées aux entreprises ou versions expérimentales — vous pouvez déployer une archive tar directement sur un serveur Twenty.
### Prérequis
Avant le déploiement, vous avez besoin d'un remote configuré pointant vers le serveur cible. Les remotes stockent localement l'URL du serveur et les informations d'authentification dans `~/.twenty/config.json`.
Ajouter un remote :
```bash filename="Terminal" theme={null}
yarn twenty remote:add --url https://your-twenty-server.com --as production
```
### Déploiement
Compilez et téléversez votre application sur le serveur en une seule étape :
```bash filename="Terminal" theme={null}
yarn twenty app:publish --private
# To deploy to a specific remote:
# yarn twenty app:publish --private --remote production
```
### Partage d'une application déployée
Le partage d'applications privées (tarball) entre espaces de travail est une fonctionnalité **Enterprise**. L'onglet **Distribution** affichera une invite de mise à niveau au lieu des contrôles de partage jusqu'à ce que votre espace de travail dispose d'une clé Enterprise valide. Accédez à [Paramètres > Panneau d'administration > Enterprise](/settings/admin-panel#enterprise) pour l'activer.
Les applications au format tarball ne sont pas répertoriées dans la place de marché publique, donc les autres espaces de travail sur le même serveur ne les découvriront pas en parcourant. Une fois que votre espace de travail est abonné à l'offre Enterprise, vous pouvez partager une application déployée comme suit :
1. Allez dans **Paramètres > Applications > Inscriptions** et ouvrez votre application
2. Dans l'onglet **Distribution**, cliquez sur **Copier le lien de partage**
3. Partagez ce lien avec des utilisateurs sur d'autres espaces de travail — il les amène directement à la page d'installation de l'application
Le lien de partage utilise l'URL de base du serveur (sans sous-domaine d'espace de travail) afin qu'il fonctionne pour tout espace de travail sur le serveur.
### Gestion des versions
Lors de la mise à jour d'une application au format tarball déjà déployée, le serveur exige que la `version` dans `package.json` soit **strictement supérieure** (selon l'ordre [SemVer](https://semver.org)) à la version actuellement déployée. Le redéploiement de la même version, ou la tentative d’en pousser une inférieure, est refusé avant que l’archive tar ne soit stockée — vous verrez une erreur `VERSION_ALREADY_EXISTS` émise par la CLI.
Pour publier une mise à jour :
1. Incrémentez le champ `version` dans votre `package.json` (par ex. `1.2.3` → `1.2.4`, `1.3.0` ou `2.0.0`)
2. Exécutez `yarn twenty app:publish --private` (ou `yarn twenty app:publish --private --remote production`)
3. Les espaces de travail qui ont installé l’application et y ont activé la mise à niveau automatique (dans l’onglet Paramètres de l’application) sont mis à niveau automatiquement en arrière-plan ; les autres verront la mise à niveau disponible dans leurs paramètres
Les tags de préversion fonctionnent comme prévu : incrémenter `1.0.0-rc.1` → `1.0.0-rc.2` est autorisé, et une version finale telle que `1.0.0` est correctement reconnue comme supérieure à `1.0.0-rc.5`. La version dans `package.json` doit elle-même être une chaîne SemVer valide.
### Compatibilité des versions du serveur
Si votre application utilise une fonctionnalité introduite dans une version spécifique du serveur Twenty (par exemple, des fournisseurs OAuth ajoutés en v2.3.0), vous devez déclarer la version minimale du serveur requise par votre application en utilisant le champ `engines.twenty` dans `package.json`:
```json filename="package.json" theme={null}
{
"name": "twenty-my-app",
"version": "1.0.0",
"engines": {
"node": "^24.5.0",
"twenty": ">=2.3.0"
}
}
```
La valeur est une [plage semver](https://github.com/npm/node-semver#ranges) standard. Modèles courants:
| Plage | Signification |
| ----------------- | ------------------------------------------------------------------- |
| `>=2.3.0` | Tout serveur à partir de 2.3.0 |
| `>=2.3.0 \<3.0.0` | 2.3.0 ou ultérieure, mais inférieure à la prochaine version majeure |
| `^2.3.0` | Identique à `>=2.3.0 \<3.0.0` |
**Ce qui se passe lors du déploiement et de l'installation:**
* Si `engines.twenty` est défini et que la version du serveur cible ne satisfait pas la plage, le déploiement (chargement du tarball) ou l'installation est refusé avec une erreur `SERVER_VERSION_INCOMPATIBLE` et un message indiquant à la fois la plage requise et la version réelle du serveur.
* Si `engines.twenty` est **non défini**, l'application est acceptée sur n'importe quelle version du serveur (rétrocompatible avec les applications existantes).
* Si le serveur n'a pas de `APP_VERSION` configuré, la vérification est ignorée.
Le serveur est l'autorité de référence pour la vérification — il valide `engines.twenty` tant lors du chargement du tarball que lors de l'installation dans l'espace de travail. Si vous déployez un tarball hors bande ou installez depuis la place de marché, le serveur applique toujours la compatibilité.
## CI/CD automatisés (workflows préconfigurés)
Les applications générées avec `create-twenty-app` sont livrées avec trois workflows GitHub Actions prêts à l’emploi, sous `.github/workflows/`. L’intégration continue (CI) s’exécute sans configuration, le déploiement continu (CD) ne nécessite qu’un seul secret, et la publication sur npm requiert une configuration unique de npm trusted-publisher.
### CI — `ci.yml`
Il exécute automatiquement vos tests d’intégration à chaque push sur `main` et sur les pull requests.
**Ce que cela fait:**
1. Récupère le code source de votre application.
2. Lance une instance de test Twenty isolée à l’aide de l’action composite `twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main` (l’équivalent CI de `yarn twenty docker:start --test`).
3. Active Corepack, configure Node.js à partir de votre `.nvmrc` et installe les dépendances avec `yarn install --immutable`.
4. Exécute `yarn test`, en passant `TWENTY_API_URL` et `TWENTY_API_KEY` depuis l’instance lancée pour que vos tests puissent communiquer avec un serveur réel.
**Paramètres de configuration:**
* `TWENTY_VERSION` (variable d’environnement, par défaut `latest`) — figez la version du serveur Twenty utilisée en CI en la modifiant dans `ci.yml`.
* La concurrence est regroupée par `github.ref` et annule les exécutions en cours lors de nouveaux push.
Aucun secret n’est requis — l’instance de test est éphémère et n’existe que pendant la durée du job.
### CD — `cd.yml`
Déploie votre application vers un serveur Twenty configuré à chaque push sur `main`, et éventuellement depuis une pull request lorsque le label `deploy` est appliqué.
**Ce que cela fait:**
1. Récupère la tête de la PR (pour les PR étiquetées) ou le commit poussé.
2. Exécute `twentyhq/twenty/.github/actions/deploy-twenty-app@main` — l’équivalent CI de `yarn twenty app:publish --private`.
3. Exécute `twentyhq/twenty/.github/actions/install-twenty-app@main` afin que la version nouvellement déployée soit installée dans l’espace de travail cible.
**Configuration requise:**
| Paramètre | Où | Objectif |
| ----------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `TWENTY_DEPLOY_URL` | `env` dans `cd.yml` (par défaut `http://localhost:3000`) | Le serveur Twenty vers lequel déployer. Remplacez ceci par l’URL réelle de votre serveur avant la première utilisation. |
| `TWENTY_DEPLOY_API_KEY` | Dépôt GitHub **Settings → Secrets and variables → Actions** | Clé API avec la permission de déployer sur le serveur cible. |
La valeur par défaut de `TWENTY_DEPLOY_URL`, `http://localhost:3000`, est un espace réservé — elle n’atteindra rien depuis un runner hébergé par GitHub. Remplacez-la par l’URL publique de votre serveur (ou utilisez un runner auto-hébergé avec accès réseau) avant d’activer la CD.
**Déclencher un déploiement de prévisualisation depuis une PR:**
Ajoutez le label `deploy` à une pull request. La condition `if:` dans `cd.yml` exécutera le job pour cette PR en utilisant le commit de tête de la PR, vous permettant de valider une modification sur le serveur cible avant la fusion.
### Publication — `publish.yml`
Publie votre application sur npm avec provenance lorsque vous poussez une étiquette de version (par exemple `v1.0.0`), ou lorsque vous exécutez manuellement le workflow depuis l’onglet Actions.
**Ce que cela fait:**
1. Récupère votre application, configure Node.js et met à jour npm (la publication de confiance nécessite npm 11.5.1 ou une version ultérieure).
2. Exécute `yarn twenty app:publish`, qui génère l’application et publie `.twenty/output` sur npm. En CI, il ajoute automatiquement `--provenance` et `--access public`, de sorte qu’aucun indicateur n’est nécessaire dans le workflow.
**Configuration unique :**
Sur npmjs.com, ouvrez votre package > **Settings → Trusted Publisher** et enregistrez ce dépôt avec le workflow `publish.yml` (voir la [documentation npm sur la publication de confiance](https://docs.npmjs.com/trusted-publishers)). La publication avec provenance certifie quel dépôt GitHub a construit le package, ce qui est aussi la façon de revendiquer la propriété de votre application dans une marketplace Twenty.
npm n’accepte la provenance que depuis des dépôts sources **publics**. Si vous publiez depuis un dépôt privé, npm rejette le bundle de provenance OIDC avec une erreur `E422 ... Erreur « Unsupported GitHub Actions source repository visibility: "private"` ». Pour publier depuis un dépôt privé, désactivez la provenance en définissant `TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'` dans la variable `env` de l’étape de publication (un indice commenté est inclus dans le fichier `publish.yml` généré automatiquement) :
```yaml filename=".github/workflows/publish.yml" theme={null}
- name: Publish to npm
env:
TWENTY_APP_PUBLISH_DISABLE_PROVENANCE: 'true'
run: yarn twenty app:publish
```
### Épingler les actions réutilisables
Les workflows `ci.yml` et `cd.yml` référencent des actions réutilisables sur `@main`, de sorte que les mises à jour des actions dans le dépôt `twentyhq/twenty` sont récupérées automatiquement. Si vous souhaitez des builds déterministes, remplacez `@main` par un SHA de commit ou un tag de version sur chaque ligne `uses:`.
## Publication sur npm
Publier sur npm rend votre application découvrable dans la marketplace Twenty. N'importe quel espace de travail Twenty peut parcourir, installer et mettre à niveau des applications de la marketplace directement depuis l'interface utilisateur.
### Prérequis
* Un compte [npm](https://www.npmjs.com)
* Le mot-clé `twenty-app` dans le tableau `keywords` de votre `package.json` (à ajouter manuellement — il n'est pas inclus par défaut dans le modèle `create-twenty-app`)
```json filename="package.json" theme={null}
{
"name": "twenty-app-postcard-sender",
"version": "1.0.0",
"keywords": ["twenty-app"]
}
```
### Métadonnées de la marketplace
La configuration `defineApplication()` prend en charge des champs optionnels qui contrôlent la façon dont votre application apparaît sur la place de marché. Utilisez `logo` et `galleryImages` pour référencer des images depuis le dossier `public/` :
```ts src/application-config.ts theme={null}
export default defineApplication({
universalIdentifier: '...',
displayName: 'My App',
description: 'A great app',
logo: 'public/logo.png',
galleryImages: [
'public/screenshot-1.png',
'public/screenshot-2.png',
],
});
```
Voir l'[accordéon defineApplication](/l/fr/developers/extend/apps/config/application#marketplace-metadata) dans la page Building Apps pour la liste complète des champs de la place de marché (`author`, `category`, `aboutDescription`, `websiteUrl`, `termsUrl`, etc.).
#### Dimensions recommandées pour les images de la galerie
La place de marché affiche `galleryImages` dans un conteneur fixe `8:5` (par exemple, `1600×1000 px`).
Les images de la galerie, quel que soit leur ratio d'aspect, sont affichées en entier et ne sont jamais recadrées, mais tout ce qui est nettement plus haut ou plus étroit que `8:5` affichera des bandes vides sur les côtés.
#### Limite de taille d’image
Le `logo` et chaque fichier `galleryImages` ne doivent pas dépasser **10 Mo**. Les fichiers plus volumineux sont ignorés lorsque la place de marché réhéberge vos ressources publiées, ils ne seront donc pas affichés.
### Publier
```bash filename="Terminal" theme={null}
yarn twenty app:publish
```
Pour publier sous un dist-tag spécifique (par exemple, `beta` ou `next`) :
```bash filename="Terminal" theme={null}
yarn twenty app:publish --tag beta
```
### Comment fonctionne la découverte de la place de marché
Le serveur Twenty synchronise son catalogue de la place de marché à partir du registre npm **toutes les heures**.
Vous pouvez déclencher la synchronisation immédiatement au lieu d'attendre :
```bash filename="Terminal" theme={null}
yarn twenty dev:catalog-sync
# To target a specific remote:
# yarn twenty dev:catalog-sync --remote production
```
Les métadonnées affichées dans la marketplace proviennent de votre configuration `defineApplication()` — voir [Métadonnées de la marketplace](#marketplace-metadata) ci-dessus.
Si votre application ne définit pas de `aboutDescription` dans `defineApplication()`, la place de marché utilisera automatiquement le `README.md` de votre package depuis npm comme contenu de la page À propos. Cela signifie que vous pouvez maintenir un seul README à la fois pour npm et pour la place de marché Twenty. Si vous souhaitez une description différente dans la place de marché, définissez explicitement `aboutDescription`.
### Publication via CI
Le workflow `publish.yml` préconfiguré décrit ci-dessus publie automatiquement sur npm lors des tags de version, avec provenance. Comme `yarn twenty app:publish` ajoute `--provenance` et `--access public` pour vous lorsqu’il s’exécute en CI, le workflow n’a besoin d’aucune option npm — seulement de la configuration unique de Trusted Publisher.
Pour d’autres systèmes de CI (GitLab CI, CircleCI, etc.), exécutez `yarn install` puis `yarn twenty app:publish`. La provenance est émise lorsque l’environnement peut générer un jeton OIDC et est ignorée automatiquement dans le cas contraire.
La **provenance npm** ajoute un badge de confiance à votre fiche npm, permettant aux utilisateurs de vérifier que le package a été construit à partir d’un commit spécifique dans un pipeline CI public. C’est également ce qui vous permet de revendiquer la propriété de votre application dans une marketplace Twenty. Voir la [documentation npm sur la provenance](https://docs.npmjs.com/generating-provenance-statements) pour plus de détails.
## Installation des applications
Une fois qu'une application est publiée (npm) ou déployée (tarball), les espaces de travail peuvent l'installer via l'interface utilisateur.
Accédez à la page **Paramètres > Applications** dans Twenty, où les applications de la place de marché et celles déployées en tarball peuvent être parcourues et installées.
Vous pouvez également installer des applications depuis la ligne de commande :
```bash filename="Terminal" theme={null}
yarn twenty app:install
```
Le serveur applique le versionnement SemVer à l’installation, en reprenant les mêmes règles que lors du déploiement :
* L’installation de la même version déjà installée dans votre espace de travail est refusée avec une erreur `APP_ALREADY_INSTALLED`.
* L’installation d’une version inférieure à celle actuellement installée est refusée avec une erreur `CANNOT_DOWNGRADE_APPLICATION`.
Pour installer une version plus récente, déployez-la ou publiez-la d’abord, puis relancez `yarn twenty app:install`.