Prerequisiti
- Node.js 24+ — Scarica
- Yarn 4 — incluso con Node.js tramite Corepack. Abilitalo:
corepack enable - Docker — Scarica. Necessario per eseguire un server Twenty locale. Salta se hai già Twenty in esecuzione altrove.
| 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: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-deve la avvia sulla porta2020. 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.
- Email:
tim@apple.dev - Password:
tim@apple.dev
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.Fase 3 — Sincronizza le tue modifiche
Questo è il ciclo interno in cui passerai la maggior parte del tempo.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.
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:
| 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. |
--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 singoloexport 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 |
Prossimi passaggi
Configurazione
Identità dell’applicazione, ruolo predefinito, hook di installazione, asset pubblici.
Dati
Oggetti, campi e relazioni bidirezionali.
Logica
Funzioni logiche, skill, agenti e connessioni OAuth.
Layout
Viste, navigazione, layout di pagina, componenti front-end.
Operazioni
CLI, test, remoti, CI e pubblicazione della tua app.