Pubblicazione

​

Panoramica

• Distribuisci un tarball — carica la tua app direttamente su un server Twenty specifico per uso interno o privato.
• Pubblica su npm — elenca la tua app nel marketplace di Twenty affinché qualsiasi spazio di lavoro possa scoprirla e installarla.

​

Compilazione della tua app

yarn twenty dev:build

​

Distribuzione su un server (tarball)

​

Prerequisiti

yarn twenty remote:add --url https://your-twenty-server.com --as production

​

Distribuzione

yarn twenty app:publish --private
# To deploy to a specific remote:
# yarn twenty app:publish --private --remote production

​

Condivisione di un’app distribuita

1. Vai su Impostazioni > Applicazioni > Registrazioni e apri la tua app
2. Nella scheda Distribuzione, fai clic su Copia link di condivisione
3. Condividi questo link con utenti su altri spazi di lavoro — li porterà direttamente alla pagina di installazione dell’app

​

Gestione delle versioni

1. Incrementa il campo version nel tuo package.json (ad es. 1.2.3 → 1.2.4, 1.3.0 o 2.0.0).
2. Esegui yarn twenty app:publish --private (oppure yarn twenty app:publish --private --remote production)
3. Gli spazi di lavoro che hanno l’app installata vedranno l’aggiornamento disponibile nelle proprie impostazioni

​

Compatibilità della versione del server

{
  "name": "twenty-my-app",
  "version": "1.0.0",
  "engines": {
    "node": "^24.5.0",
    "twenty": ">=2.3.0"
  }
}

• Se engines.twenty è impostato e la versione del server di destinazione non soddisfa l’intervallo, il deploy (caricamento del tarball) o l’installazione vengono rifiutati con un errore SERVER_VERSION_INCOMPATIBLE e un messaggio che indica sia l’intervallo richiesto sia la versione effettiva del server.
• Se engines.twenty non è impostato, l’app è accettata su qualsiasi versione del server (retrocompatibile con le app esistenti).
• Se sul server non è configurata APP_VERSION, il controllo viene ignorato.

​

CI/CD automatizzati (workflow preconfigurati)

​

CI — ci.yml

1. Esegue il checkout del codice sorgente della tua app.
2. Avvia un’istanza di test isolata di Twenty utilizzando l’azione composita twentyhq/twenty/.github/actions/spawn-twenty-app-dev-test@main (l’equivalente per la CI di yarn twenty docker:start --test).
3. Abilita Corepack, configura Node.js dal tuo .nvmrc e installa le dipendenze con yarn install --immutable.
4. Esegue yarn test, passando TWENTY_API_URL e TWENTY_API_KEY dall’istanza avviata affinché i tuoi test possano comunicare con un server reale.

• TWENTY_VERSION (variabile di ambiente, predefinito latest) — fissa la versione del server Twenty usata nella CI modificando questo valore in ci.yml.
• La concorrenza è raggruppata per github.ref e annulla le esecuzioni in corso in caso di nuovi push.

​

CD — cd.yml

1. Esegue il checkout della testa della PR (per le PR etichettate) oppure del commit inviato.
2. Esegue twentyhq/twenty/.github/actions/deploy-twenty-app@main — l’equivalente per la CI di yarn twenty app:publish --private.
3. Esegue twentyhq/twenty/.github/actions/install-twenty-app@main in modo che la versione appena distribuita venga installata nello spazio di lavoro di destinazione.

​

Bloccare le azioni riutilizzabili

​

Pubblicazione su npm

​

Requisiti

• Un account npm
• La parola chiave twenty-app nell’array keywords del tuo package.json (aggiungila manualmente — non è inclusa per impostazione predefinita nel template create-twenty-app)

{
  "name": "twenty-app-postcard-sender",
  "version": "1.0.0",
  "keywords": ["twenty-app"]
}

​

Metadati del marketplace

export default defineApplication({
  universalIdentifier: '...',
  displayName: 'My App',
  description: 'A great app',
  logoUrl: 'public/logo.png',
  screenshots: [
    'public/screenshot-1.png',
    'public/screenshot-2.png',
  ],
});

​

Dimensioni consigliate degli screenshot

​

Pubblica

yarn twenty app:publish

yarn twenty app:publish --tag beta

​

Come funziona l’individuazione nel marketplace

yarn twenty dev:catalog-sync
# To target a specific remote:
# yarn twenty dev:catalog-sync --remote production

​

Pubblicazione con CI

name: Publish
on:
  release:
    types: [published]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "24"
          registry-url: https://registry.npmjs.org
      - run: yarn install --immutable
      - run: npx twenty dev:build
      - run: npm publish --provenance --access public
        working-directory: .twenty/output

​

Installazione delle app

yarn twenty app:install