---
title: Pubblicazione
description: Distribuisci la tua app Twenty nel marketplace oppure distribuiscila internamente.
---

<Warning>
Le app sono attualmente in fase alfa. La funzionalità è funzionante ma ancora in evoluzione.
</Warning>

## Panoramica

Una volta che la tua app è stata [compilata e testata localmente](/l/it/developers/extend/apps/building), hai due modalità per distribuirla:

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

Entrambi i percorsi partono dalla stessa fase di **build**.

## Compilazione della tua app

Il comando `build` compila i tuoi sorgenti TypeScript, transpila le funzioni di logica e i componenti front-end e genera un `manifest.json` che descrive i contenuti della tua app:

```bash filename="Terminal"
yarn twenty build
```

L'output viene scritto in `.twenty/output/`. Questa directory contiene tutto il necessario per la distribuzione: codice compilato, risorse, il manifest e una copia del tuo `package.json`.

Per creare anche un tarball `.tgz` (usato internamente dal comando di deploy o per la distribuzione manuale):

```bash filename="Terminal"
yarn twenty build --tarball
```

## 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](https://www.npmjs.com)
* La parola chiave `twenty-app` **deve** essere elencata nell'array `keywords` del tuo `package.json`

### Aggiunta della parola chiave richiesta

Il marketplace di Twenty individua le app cercando nel registro npm i pacchetti con la parola chiave `twenty-app`. Aggiungila al tuo `package.json`:

```json filename="package.json"
{
  "name": "twenty-app-postcard-sender",
  "version": "1.0.0",
  "keywords": ["twenty-app"],
  ...
}
```

<Note>
Il marketplace cerca `keywords:twenty-app` sul registro npm. Senza questa parola chiave, il tuo pacchetto non apparirà nel marketplace anche se ha il prefisso nel nome `twenty-app-`.
</Note>

### Passaggi

1. **Compila la tua app:**

```bash filename="Terminal"
yarn twenty build
```

2. **Pubblica su npm:**

```bash filename="Terminal"
yarn twenty publish
```

Questo esegue `npm publish` dalla directory `.twenty/output/`.

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

```bash filename="Terminal"
yarn twenty publish --tag beta
```

### Come funziona l'individuazione nel marketplace

Il server Twenty sincronizza il proprio catalogo del marketplace dal registro npm **ogni ora**:

1. Cerca tutti i pacchetti npm con `keywords:twenty-app`
2. Per ogni pacchetto, recupera il `manifest.json` dalla CDN di npm
3. I metadati dell'app (nome, descrizione, autore, logo, screenshot, categoria) vengono estratti dal manifest e visualizzati nel marketplace

Dopo la pubblicazione, la tua app può impiegare fino a un'ora per apparire nel marketplace. Per attivare subito la sincronizzazione invece di attendere la prossima esecuzione oraria:

```bash filename="Terminal"
yarn twenty catalog-sync
```

Per puntare a un remote specifico:

```bash filename="Terminal"
yarn twenty catalog-sync -r production
```

I metadati mostrati nel marketplace provengono dalla chiamata a `defineApplication()` nel codice sorgente della tua app — campi come `displayName`, `description`, `author`, `category`, `logoUrl`, `screenshots`, `aboutDescription`, `websiteUrl` e `termsUrl`.

### Pubblicazione con CI

Il progetto generato include un workflow di GitHub Actions che pubblica a ogni release:

```yaml filename=".github/workflows/publish.yml"
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 build
      - run: npm publish --provenance --access public
        working-directory: .twenty/output
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

Per altri sistemi CI (GitLab CI, CircleCI, ecc.), si applicano gli stessi tre comandi: `yarn install`, `yarn twenty build`, quindi `npm publish` da `.twenty/output`.

<Tip>
**npm provenance** è opzionale ma consigliata. La pubblicazione con `--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. Consulta la [documentazione su npm provenance](https://docs.npmjs.com/generating-provenance-statements) per le istruzioni di configurazione.
</Tip>

## 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:

```bash filename="Terminal"
yarn twenty remote add --url https://your-twenty-server.com --as production
```

Per un server di sviluppo locale:

```bash filename="Terminal"
yarn twenty remote add --local --as local
```

Puoi anche autenticarti con una chiave API per ambienti non interattivi:

```bash filename="Terminal"
yarn twenty remote add --url https://your-twenty-server.com --token <api-key> --as production
```

Gestisci i tuoi remote:

```bash filename="Terminal"
yarn twenty remote list       # List all configured remotes
yarn twenty remote switch prod # Set the default remote
yarn twenty remote status     # Show active remote and auth status
yarn twenty remote remove old # Remove a remote
```

### Distribuzione

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

```bash filename="Terminal"
yarn twenty deploy
```

Questo compila l'app con `--tarball`, quindi carica il tarball sul remote predefinito tramite un upload multipart GraphQL.

Per distribuire su un remote specifico:

```bash filename="Terminal"
yarn twenty deploy -r production
```

### Condivisione di un'app distribuita

Le app in formato tarball non sono elencate nel marketplace pubblico, quindi altri spazi di lavoro sullo stesso server non le troveranno navigando. Per condividere 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

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

Per rilasciare un aggiornamento:

1. Incrementa il campo `version` nel tuo `package.json`
2. Esegui `yarn twenty deploy` (oppure `yarn twenty deploy -r production`)
3. Gli spazi di lavoro che hanno l'app installata vedranno l'aggiornamento disponibile nelle proprie impostazioni

## Installazione delle app

Una volta che un'app è stata pubblicata (npm) o distribuita (tarball), gli spazi di lavoro la installano tramite l'interfaccia utente:

```bash filename="Terminal"
yarn twenty install
```

Oppure dalla pagina **Impostazioni > Applicazioni** nell'interfaccia di Twenty, dove è possibile sfogliare e installare sia le app del marketplace sia quelle distribuite tramite tarball.

## Categorie di distribuzione delle app

Twenty organizza le app in tre categorie in base a come vengono distribuite:

| Categoria             | Come funziona                                                                                                                                    | Visibile nel marketplace? |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
| **Sviluppo**          | App in modalità di sviluppo locale eseguite tramite `yarn twenty dev`. Usate per la compilazione e i test.                                       | No                        |
| **Pubblicate (npm)**  | App pubblicate su npm con la parola chiave `twenty-app`. Elencate nel marketplace per l'installazione da parte di qualsiasi spazio di lavoro.    | Sì                        |
| **Interne (tarball)** | App distribuite tramite tarball su un server specifico. Disponibili solo per gli spazi di lavoro su quel server tramite un link di condivisione. | No                        |

<Tip>
Inizia in modalità **Sviluppo** mentre crei la tua app. Quando è pronta, scegli **Pubblicata** (npm) per un'ampia distribuzione oppure **Interna** (tarball) per una distribuzione privata.
</Tip>

## Riferimento CLI

| Comando                     | Descrizione                                                        | Flag principali                                      |
| --------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------- |
| `yarn twenty build`         | Compila l'app e genera il manifest                                 | `--tarball` — crea anche un pacchetto `.tgz`         |
| `yarn twenty publish`       | Compila e pubblica su npm                                          | `--tag <tag>` — dist-tag npm (ad es. `beta`, `next`) |
| `yarn twenty deploy`        | Compila e carica un tarball su un server                           | `-r, --remote <name>` — remote di destinazione       |
| `yarn twenty catalog-sync`  | Attiva la sincronizzazione del catalogo del marketplace sul server | `-r, --remote <name>` — remote di destinazione       |
| `yarn twenty install`       | Installa un'app distribuita su uno spazio di lavoro                | `-r, --remote <name>` — remote di destinazione       |
| `yarn twenty dev`           | Osserva e sincronizza le modifiche locali                          | Usa il remote predefinito                            |
| `yarn twenty remote add`    | Aggiungi una connessione al server                                 | `--url`, `--token`, `--as`, `--local`, `--port`      |
| `yarn twenty remote list`   | Elenca i remote configurati                                        | —                                                    |
| `yarn twenty remote switch` | Imposta il remote predefinito                                      | —                                                    |
| `yarn twenty remote status` | Mostra lo stato della connessione                                  | —                                                    |
| `yarn twenty remote remove` | Rimuovi un remote                                                  | —                                                    |
