Pubblicazione

Panoramica

Una volta che la tua app è stata compilata e testata localmente, hai due modalità per distribuirla:

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.

Entrambi i percorsi partono dalla stessa fase di build.

Compilazione della tua app

Esegui il comando di build per compilare la tua app e generare un manifest.json pronto per la distribuzione:

yarn twenty dev:build

Questo compila i sorgenti TypeScript, transpila le funzioni di logica e i componenti front-end e scrive tutto in .twenty/output/. Aggiungi --tarball per produrre anche un pacchetto .tgz per la distribuzione manuale o per il comando di publish.

Distribuzione su un server (tarball)

Per le app che non vuoi rendere pubbliche — strumenti proprietari, integrazioni solo aziendali o build sperimentali — puoi distribuire un tarball direttamente su un server Twenty.

Prerequisiti

Prima della distribuzione, ti serve un remote configurato che punti al server di destinazione. I remote memorizzano localmente l’URL del server e le credenziali di autenticazione in ~/.twenty/config.json. Aggiungi un remote:

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

Distribuzione

Compila e carica la tua app sul server in un solo passaggio:

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

Condivisione di un’app distribuita

La condivisione di app private (tarball) tra spazi di lavoro è una funzionalità Enterprise. La scheda Distribuzione mostrerà un invito all’aggiornamento al posto dei controlli di condivisione finché il tuo spazio di lavoro non dispone di una chiave Enterprise valida. Vedi Impostazioni > Pannello di amministrazione > Enterprise per attivarla.

Le app in formato tarball non sono elencate nel marketplace pubblico, quindi altri spazi di lavoro sullo stesso server non le troveranno navigando. Una volta che il tuo spazio di lavoro è sul piano Enterprise, puoi condividere un’app distribuita in questo modo:

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

Il link di condivisione utilizza l’URL di base del server (senza alcun sottodominio dello spazio di lavoro) così funziona per qualsiasi spazio di lavoro sul server.

Gestione delle versioni

Quando si aggiorna un’app in formato tarball già distribuita, il server richiede che la version in package.json sia strettamente superiore (per l’ordinamento semver) rispetto alla versione attualmente distribuita. Eseguire nuovamente il deploy della stessa versione, o pubblicarne una inferiore, viene rifiutato prima che il tarball venga archiviato — vedrai un errore VERSION_ALREADY_EXISTS nella CLI. Per rilasciare un aggiornamento:

Incrementa il campo version nel tuo package.json (ad es. 1.2.3 → 1.2.4, 1.3.0 o 2.0.0).
Esegui yarn twenty app:publish --private (oppure yarn twenty app:publish --private --remote production)
Gli spazi di lavoro che hanno installato l’app e abilitato l’aggiornamento automatico (nella scheda Impostazioni dell’app) vengono aggiornati automaticamente in secondo piano; gli altri vedranno l’aggiornamento disponibile nelle loro impostazioni

I tag di pre-release funzionano come previsto: incrementare 1.0.0-rc.1 → 1.0.0-rc.2 è consentito e una release finale come 1.0.0 viene correttamente riconosciuta come superiore a 1.0.0-rc.5. La versione in package.json deve essere essa stessa una stringa semver valida.

Compatibilità della versione del server

Se la tua app utilizza una funzionalità introdotta in una specifica versione del server Twenty (ad esempio, i provider OAuth aggiunti nella v2.3.0), dovresti dichiarare la versione minima del server richiesta dalla tua app utilizzando il campo engines.twenty in package.json:

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

Il valore è un intervallo semver standard. Modelli comuni:

Intervallo	Significato
`>=2.3.0`	Qualsiasi server a partire dalla 2.3.0
`>=2.3.0 \<3.0.0`	2.3.0 o successive, ma precedenti alla prossima versione major
`^2.3.0`	Equivale a `>=2.3.0 \<3.0.0`

Cosa succede durante il deploy e l’installazione:

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.

Il server è l’autorità di controllo — convalida engines.twenty sia durante il caricamento del tarball sia durante l’installazione nello spazio di lavoro. Se distribuisci un tarball out-of-band o installi dal marketplace, il server continua comunque a imporre la compatibilità.

CI/CD automatizzati (workflow preconfigurati)

Le app generate con create-twenty-app includono tre workflow di GitHub Actions pronti all’uso, nella cartella .github/workflows/. L’esecuzione della CI non richiede alcuna configurazione, la CD richiede un solo secret e la pubblicazione su npm richiede una configurazione una tantum di npm trusted-publisher.

CI — `ci.yml`

Esegue automaticamente i test di integrazione a ogni push su main e sulle pull request. Cosa fa:

Esegue il checkout del codice sorgente della tua app.
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).
Abilita Corepack, configura Node.js dal tuo .nvmrc e installa le dipendenze con yarn install --immutable.
Esegue yarn test, passando TWENTY_API_URL e TWENTY_API_KEY dall’istanza avviata affinché i tuoi test possano comunicare con un server reale.

Opzioni di configurazione:

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.

Non sono necessari Secrets — l’istanza di test è effimera ed esiste solo per la durata del job.

CD — `cd.yml`

Esegue il deploy della tua app su un server Twenty configurato a ogni push su main e, facoltativamente, da una pull request quando viene applicata l’etichetta deploy. Cosa fa:

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

Configurazione richiesta:

Impostazione	Dove	Scopo
`TWENTY_DEPLOY_URL`	`env` in `cd.yml` (predefinito `http://localhost:3000`)	Il server Twenty su cui effettuare il deploy. Modificalo con l’URL reale del tuo server prima del primo utilizzo.
`TWENTY_DEPLOY_API_KEY`	Repository GitHub Settings → Secrets and variables → Actions	Chiave API con autorizzazione di deploy sul server di destinazione.

Il valore predefinito di TWENTY_DEPLOY_URL, http://localhost:3000, è un segnaposto — non raggiungerà alcuna risorsa da un runner ospitato su GitHub. Aggiornalo all’URL pubblico del tuo server (oppure usa un runner self-hosted con accesso di rete) prima di abilitare il CD.

Attivare un deploy di anteprima da una PR: Aggiungi l’etichetta deploy a una pull request. La condizione if: in cd.yml eseguirà il job per quella PR utilizzando il commit di testa della PR, permettendoti di convalidare una modifica sul server di destinazione prima del merge.

Pubblica — `publish.yml`

Pubblica la tua app su npm con attestazione di provenienza quando esegui il push di un tag di versione (ad es. v1.0.0), oppure quando esegui manualmente il workflow dalla scheda Actions. Cosa fa:

Clona la tua app, configura Node.js e aggiorna npm (la pubblicazione attendibile richiede npm 11.5.1 o versioni successive).
Esegue yarn twenty app:publish, che crea la build dell’app e pubblica .twenty/output su npm. In CI aggiunge automaticamente --provenance e --access public, quindi non sono necessari flag nel workflow.

Impostazione una tantum: Su npmjs.com apri il tuo pacchetto > Settings → Trusted Publisher e registra questo repository con il workflow publish.yml (consulta la documentazione su npm trusted publishing). La pubblicazione con provenance certifica quale repository GitHub ha creato il pacchetto ed è anche il modo in cui dichiari la proprietà della tua app in un marketplace Twenty.

Bloccare le azioni riutilizzabili

I workflow ci.yml e cd.yml fanno riferimento ad azioni riutilizzabili a @main, quindi gli aggiornamenti delle azioni nel repository twentyhq/twenty vengono recepiti automaticamente. Se desideri build deterministiche, sostituisci @main con uno SHA di commit o un tag di release in ciascuna riga uses:.

Pubblicazione su npm

La pubblicazione su npm rende la tua app scopribile nel marketplace di Twenty. Qualsiasi spazio di lavoro Twenty può sfogliare, installare e aggiornare le app del marketplace direttamente dall’interfaccia utente.

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

La configurazione defineApplication() supporta campi opzionali che controllano come la tua app appare nel marketplace. Usa logo e galleryImages per fare riferimento alle immagini nella cartella public/:

src/application-config.ts

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

Vedi l’accordion defineApplication nella pagina Building Apps per l’elenco completo dei campi del marketplace (author, category, aboutDescription, websiteUrl, termsUrl, ecc.).

Dimensioni consigliate delle immagini della galleria

Il marketplace visualizza le galleryImages in un contenitore 8:5 fisso (ad esempio, 1600×1000 px).

Le immagini della galleria di qualsiasi rapporto d’aspetto vengono visualizzate per intero e non vengono mai ritagliate, ma tutto ciò che è significativamente più alto o più stretto di 8:5 mostrerà bande vuote ai lati.

Limite dimensione immagine

Il file logo e ciascun file di galleryImages non devono superare 10 MB. I file più grandi vengono ignorati quando il marketplace ripubblica le tue risorse pubblicate, quindi non verranno visualizzati.

Pubblica

yarn twenty app:publish

Per pubblicare con un dist-tag specifico (ad es. beta o next):

yarn twenty app:publish --tag beta

Come funziona l’individuazione nel marketplace

Il server Twenty sincronizza il proprio catalogo del marketplace dal registro npm ogni ora. Puoi attivare la sincronizzazione immediatamente invece di aspettare:

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

I metadati mostrati nel marketplace provengono dalla configurazione di defineApplication() — vedi Metadati del marketplace sopra.

Se la tua app non definisce un aboutDescription in defineApplication(), il marketplace userà automaticamente il README.md del tuo pacchetto su npm come contenuto della pagina Informazioni. Questo significa che puoi mantenere un unico README sia per npm sia per il marketplace di Twenty. Se desideri una descrizione diversa nel marketplace, imposta esplicitamente aboutDescription.

Pubblicazione con CI

Il workflow publish.yml generato dallo scaffold descritto sopra pubblica automaticamente su npm sui tag di versione, con provenance. Poiché yarn twenty app:publish aggiunge --provenance e --access public per te quando viene eseguito in CI, il workflow non ha bisogno di flag npm — serve solo l’impostazione una tantum del trusted publisher. Per altri sistemi CI (GitLab CI, CircleCI, ecc.), esegui yarn install e poi yarn twenty app:publish. La provenance viene emessa quando l’ambiente può generare un token OIDC e, in caso contrario, viene saltata automaticamente.

La npm provenance aggiunge un badge di attendibilità alla tua scheda npm, consentendo agli utenti di verificare che il pacchetto sia stato creato a partire da uno specifico commit in una pipeline CI pubblica. È anche ciò che ti permette di dichiarare la proprietà della tua app in un marketplace Twenty. Consulta la documentazione su npm provenance per maggiori dettagli.

Installazione delle app

Una volta che un’app è stata pubblicata (npm) o distribuita (tarball), gli spazi di lavoro possono installarla tramite l’interfaccia utente. Vai alla pagina Impostazioni > Applicazioni in Twenty, dove è possibile sfogliare e installare sia le app del marketplace sia quelle distribuite tramite tarball. Puoi anche installare le app dalla riga di comando:

yarn twenty app:install

Il server applica il versioning semver durante l’installazione, rispecchiando le regole del deploy:

L’installazione della stessa versione già installata nel tuo spazio di lavoro viene rifiutata con un errore APP_ALREADY_INSTALLED.
L’installazione di una versione inferiore rispetto a quella attualmente installata viene rifiutata con un errore CANNOT_DOWNGRADE_APPLICATION.

Per installare una versione più recente, effettua prima il deploy o la pubblicazione, quindi riesegui yarn twenty app:install.

Panoramica

App

API

Auto-ospitazione

Contribuire

Panoramica

Compilazione della tua app

Distribuzione su un server (tarball)

Prerequisiti

Distribuzione

Condivisione di un’app distribuita

Gestione delle versioni

Compatibilità della versione del server

CI/CD automatizzati (workflow preconfigurati)

CI — `ci.yml`

CD — `cd.yml`

Pubblica — `publish.yml`

Bloccare le azioni riutilizzabili

Pubblicazione su npm

Requisiti

Metadati del marketplace

Dimensioni consigliate delle immagini della galleria

Limite dimensione immagine

Pubblica

Come funziona l’individuazione nel marketplace

Pubblicazione con CI

Installazione delle app

​Panoramica

​Compilazione della tua app

​Distribuzione su un server (tarball)

​Prerequisiti

​Distribuzione

​Condivisione di un’app distribuita

​Gestione delle versioni

​Compatibilità della versione del server

​CI/CD automatizzati (workflow preconfigurati)

​CI — ci.yml

​CD — cd.yml

​Pubblica — publish.yml

​Bloccare le azioni riutilizzabili

​Pubblicazione su npm

​Requisiti

​Metadati del marketplace

​Dimensioni consigliate delle immagini della galleria

​Limite dimensione immagine

​Pubblica

​Come funziona l’individuazione nel marketplace

​Pubblicazione con CI

​Installazione delle app

Panoramica

Compilazione della tua app

Distribuzione su un server (tarball)

Prerequisiti

Distribuzione

Condivisione di un’app distribuita

Gestione delle versioni

Compatibilità della versione del server

CI/CD automatizzati (workflow preconfigurati)

CI — `ci.yml`

CD — `cd.yml`

Pubblica — `publish.yml`

Bloccare le azioni riutilizzabili

Pubblicazione su npm

Requisiti

Metadati del marketplace

Dimensioni consigliate delle immagini della galleria

Limite dimensione immagine

Pubblica

Come funziona l’individuazione nel marketplace

Pubblicazione con CI

Installazione delle app