Vai al contenuto principale

​
Prerequisiti

  • Node.js 24.5+ — 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.
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 1 — Crea la struttura del progetto

Crea una nuova app dal modello:
Lo scaffolder è non interattivo: il nome della directory diventa il nome dell’app. Passa --display-name e --description per personalizzare i metadati generati (puoi anche modificarli in seguito in src/constants/universal-identifiers.ts). Questo genera un progetto TypeScript in my-twenty-app/ con un application-config.ts iniziale, un ruolo predefinito, workflow CI/CD 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 scaffolder avvia un’istanza per te: con Docker in esecuzione, scarica l’immagine twentycrm/twenty-app-dev, la avvia sulla porta 2020 e autentica la CLI sullo spazio di lavoro demo prepopolato (tim@apple.dev) — non è necessario effettuare l’accesso. Per connetterti invece a un server Twenty esistente, passa --url \<your-server-url>. I server remoti eseguono l’autenticazione con OAuth: si apre un browser così puoi effettuare l’accesso e fare clic su Authorize, concedendo alla CLI l’accesso al tuo spazio di lavoro. (Puoi anche scegliere di utilizzare OAuth in locale con --authentication-method oauth — accedi con tim@apple.dev / tim@apple.dev.)
Schermata di accesso di Twenty
Schermata di autorizzazione della CLI di Twenty
Il terminale confermerà che tutto è configurato.
App creata con successo
Dopo questa fase: hai un server Twenty in esecuzione su http://localhost:2020 con la tua CLI autorizzata a sincronizzarsi con esso.
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.
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.
Output del terminale in modalità sviluppo
Apri http://localhost:2020/settings/applications#developer. Dovresti vedere la tua app sotto Your Apps.
Elenco Your Apps che mostra My twenty app
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.
Dettagli della registrazione dell'applicazione
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.
App installata
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

Usa plan e apply per eseguire la stessa pipeline una volta, senza watcher:
Tutte le modalità richiedono un remoto autenticato. Vedi Sincronizzazione e ripristino per maggiori informazioni su plan.
yarn twenty dev --once e yarn twenty dev --once --dry-run sono alias deprecati di yarn twenty apply e yarn twenty plan.

​
Opzioni della modalità di sviluppo

​
Cosa puoi creare

Le app sono composte da entità — ciascuna definita come un file TypeScript con un singolo export default: Riferimento completo: Concetti.

​
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.