twenty/packages/twenty-docs/l/it/developers/extend/apps/getting-started/quick-start.mdx

---
title: Avvio rapido
icon: rocket
description: Crea la tua prima app Twenty in pochi minuti.
---

## Prerequisiti

* **Node.js 24+** — [Scarica](https://nodejs.org/)
* **Yarn 4** — incluso con Node.js tramite Corepack. Abilitalo: `corepack enable`
* **Docker** — [Scarica](https://www.docker.com/products/docker-desktop/). Necessario per eseguire un server Twenty locale. Salta se hai già Twenty in esecuzione altrove.

La creazione di un'app Twenty ha tre fasi. Lo strumento di scaffolding le combina in un unico comando per il percorso ottimale, ma ogni fase è un concetto distinto — quando qualcosa fallisce, sapere in quale fase ti trovi indica cosa correggere.

| Fase                    | Cosa fai                                               | Strumento                     | Risultato                          |
| ----------------------- | ------------------------------------------------------ | ----------------------------- | ---------------------------------- |
| **1. Crea struttura**   | Genera il codice sorgente dell'app                     | `npx create-twenty-app`       | Un progetto TypeScript sul disco   |
| **2. Esegui un server** | Avvia un server Twenty con cui sincronizzare           | Docker + `yarn twenty server` | Un'istanza Twenty in esecuzione    |
| **3. Sincronizza**      | Sincronizza in tempo reale il tuo codice con il server | `yarn twenty dev`             | Le tue modifiche compaiono nell'UI |

---

## Fase 1 — Crea la struttura del progetto

Crea una nuova app dal modello:

```bash filename="Terminal"
npx create-twenty-app@latest my-twenty-app
```

Ti verrà chiesto un nome e una descrizione — premi **Invio** per usare i valori predefiniti. Questo genera un progetto TypeScript in `my-twenty-app/` con un `application-config.ts` iniziale, un ruolo predefinito, un workflow CI e un test di integrazione.

**Dopo questa fase:** hai il codice sorgente dell'app sulla tua macchina. Non è ancora in esecuzione — questa è la Fase 2.

---

## Fase 2 — Esegui un server Twenty locale

La tua app ha bisogno di un server Twenty con cui sincronizzarsi. Il server è un'istanza Twenty completa — UI, API GraphQL, PostgreSQL — in esecuzione in locale su Docker. Il tuo codice locale carica le sue definizioni su quel server, che le rende visibili nell'UI.

Lo strumento di scaffolding ti propone di avviarne uno per te:

> **Vuoi configurare un'istanza locale di Twenty?**

* **Sì (consigliato)** — scarica l'immagine Docker `twentycrm/twenty-app-dev` e la avvia sulla porta `2020`. Assicurati prima che Docker sia in esecuzione.
* **No** — scegli questa opzione se hai già un server Twenty a cui vuoi connetterti. Puoi collegarlo in seguito con `yarn twenty remote:add`.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/start-instance.png" alt="Avviare l'istanza locale?" />
</div>

Quando il server è attivo, si apre il browser per l'accesso. Usa l'account demo preconfigurato:

* **Email:** `tim@apple.dev`
* **Password:** `tim@apple.dev`

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/login.png" alt="Schermata di accesso di Twenty" />
</div>

Fai clic su **Authorize** nella schermata successiva — questo concede alla CLI l'accesso al tuo spazio di lavoro.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Schermata di autorizzazione della CLI di Twenty" />
</div>

Il terminale confermerà che tutto è configurato.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App creata con successo" />
</div>

**Dopo questa fase:** hai un server Twenty in esecuzione su [http://localhost:2020](http://localhost:2020) con la tua CLI autorizzata a sincronizzarsi con esso.

<Note>
Se Docker non è installato o in esecuzione, lo strumento di scaffolding ti indicherà il comando di avvio corretto per il tuo sistema operativo. Quando Docker è attivo, puoi riprendere con `yarn twenty docker:start` — non è necessario rifare lo scaffolding.
</Note>

---

## Fase 3 — Sincronizza le tue modifiche

Questo è il ciclo interno in cui passerai la maggior parte del tempo.

```bash filename="Terminal"
cd my-twenty-app
yarn twenty dev
```

Questo osserva `src/`, ricompila a ogni modifica e sincronizza il risultato con il server. Modifica un file, salvalo e in pochi secondi il server riflette la modifica. Vedrai un pannello di stato in tempo reale nel terminale.

Per un output più dettagliato (log di build, richieste di sincronizzazione, tracce di errore), aggiungi `--verbose`.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/dev.png" alt="Output del terminale in modalità sviluppo" />
</div>

Apri [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Dovresti vedere la tua app sotto **Your Apps**.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Elenco Your Apps che mostra My twenty app" />
</div>

Fai clic su **My twenty app** per vedere la sua **registrazione dell'applicazione** — un record a livello di server che descrive la tua app (nome, identificatore, credenziali OAuth, origine). Una registrazione può essere installata in più spazi di lavoro sullo stesso server.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Dettagli della registrazione dell'applicazione" />
</div>

Fai clic su **View installed app** per vedere l'installazione nello spazio di lavoro. La scheda **About** mostra la versione e le opzioni di gestione.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="App installata" />
</div>

**Dopo questa fase:** hai un ciclo di sviluppo in tempo reale. Modifica qualsiasi file in `src/` e compare nell'UI.

### Sincronizzazione una tantum per CI e script

Passa `--once` per eseguire una singola build + sincronizzazione ed uscire — stessa pipeline, nessun watcher:

```bash filename="Terminal"
yarn twenty dev --once
```

| Comando                            | Comportamento                                                                                        | Quando usarlo                                                                                  |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `yarn twenty dev`                  | Monitora e risincronizza a ogni modifica. Rimane in esecuzione finché non lo interrompi.             | Sviluppo locale interattivo.                                                                   |
| `yarn twenty dev --once`           | Singola build + sincronizzazione, termina con codice `0` in caso di successo, `1` in caso di errore. | CI, hook pre-commit, agenti IA, flussi di lavoro scriptati.                                    |
| `yarn twenty dev --once --dry-run` | Crea e stampa le modifiche ai metadati **senza applicarle**.                                         | Ispezionare quali modifiche verrebbero apportate da una sincronizzazione prima di confermarla. |

Entrambe le modalità richiedono un remoto autenticato. Vedi [Sincronizzazione e ripristino](/l/it/developers/extend/apps/operations/sync-and-recovery#previewing-changes-dry-run) per maggiori informazioni su `--dry-run`.

### Opzioni della modalità di sviluppo

| Opzione                               | Descrizione                                                                                        |
| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `--once`                              | Esegui una build e una sincronizzazione una sola volta, quindi esci.                               |
| `--dry-run`                           | Con `--once`, visualizza in anteprima le modifiche ai metadati senza applicarle. Non scrive nulla. |
| `--debounceMs \<ms>` | Imposta il ritardo di debounce delle modifiche ai file in millisecondi (predefinito: `2000`).      |
| `--verbose` / `--debug`               | Mostra log di build dettagliati, richieste di sincronizzazione e tracce di errore.                 |

## Cosa puoi creare

Le app sono composte da **entità** — ciascuna definita come un file TypeScript con un singolo `export default`:

| Entità                   | Cosa fa                                                                                                           |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| **Oggetti e campi**      | Modelli di dati personalizzati (Cartolina, Fattura, ecc.) con campi tipizzati                                     |
| **Funzioni logiche**     | TypeScript lato server attivato da route HTTP, pianificazioni cron o eventi del database                          |
| **Componenti front-end** | Componenti React che vengono renderizzati all'interno dell'UI di Twenty (pannello laterale, widget, menu comandi) |
| **Skill e agenti**       | Funzionalità di IA — istruzioni riutilizzabili e assistenti autonomi                                              |
| **Viste e navigazione**  | Viste elenco preconfigurate e voci di menu della barra laterale                                                   |
| **Layout di pagina**     | Pagine di dettaglio dei record personalizzate con schede e widget                                                 |

Riferimento completo: [Concetti](/l/it/developers/extend/apps/getting-started/concepts).

## Prossimi passaggi

<CardGroup cols={2}>
  <Card title="Configurazione" icon="screwdriver-wrench" href="/l/it/developers/extend/apps/config/overview">
    Identità dell'applicazione, ruolo predefinito, hook di installazione, asset pubblici.
  </Card>
  <Card title="Dati" icon="database" href="/l/it/developers/extend/apps/data/overview">
    Oggetti, campi e relazioni bidirezionali.
  </Card>
  <Card title="Logica" icon="bolt" href="/l/it/developers/extend/apps/logic/overview">
    Funzioni logiche, skill, agenti e connessioni OAuth.
  </Card>
  <Card title="Layout" icon="table-columns" href="/l/it/developers/extend/apps/layout/overview">
    Viste, navigazione, layout di pagina, componenti front-end.
  </Card>
  <Card title="Operazioni" icon="rocket" href="/l/it/developers/extend/apps/operations/overview">
    CLI, test, remoti, CI e pubblicazione della tua app.
  </Card>
</CardGroup>