Documentation Index
Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
Use this file to discover all available pages before exploring further.
Cosa sono le app?
Le app ti consentono di estendere Twenty con oggetti, campi, funzioni logiche, componenti front-end, competenze IA e altro ancora — il tutto gestito come codice. Invece di configurare tutto tramite l’interfaccia utente, definisci in TypeScript il modello dati e la logica e li distribuisci in uno o più spazi di lavoro.
Prerequisiti
Prima di iniziare, assicurati che quanto segue sia installato sul tuo computer:
- Node.js 24+ — Scarica qui
- Yarn 4 — Incluso con Node.js tramite Corepack. Abilitalo eseguendo
corepack enable
- Docker — Scarica qui. Necessario per eseguire un’istanza locale di Twenty. Non necessario se hai già un server Twenty in esecuzione.
Crea la tua prima app
Crea lo scheletro della tua app
Apri un terminale ed esegui:
npx create-twenty-app@latest my-twenty-app
my-twenty-app con tutto il necessario.
Configura un’istanza locale di Twenty
Lo strumento di scaffolding chiederà:
Vuoi configurare un’istanza locale di Twenty?
- Digita
yes (consigliato) — Questo scarica l’immagine Docker twenty-app-dev e avvia un server Twenty locale sulla porta 2020. Assicurati che Docker sia in esecuzione prima di continuare.
- Digita
no — Sceglilo se hai già un server Twenty in esecuzione in locale.
Accedi al tuo spazio di lavoro
Successivamente si aprirà una finestra del browser con la pagina di accesso di Twenty. Accedi con l’account demo preconfigurato:
- Email:
tim@apple.dev
- Password:
tim@apple.dev
Autorizza l’app
Dopo l’accesso, vedrai una schermata di autorizzazione. Questo consente alla tua app di interagire con il tuo spazio di lavoro.
Fai clic su Authorize per continuare.
Una volta autorizzato, il terminale confermerà che tutto è configurato.
Inizia a sviluppare
Entra nella nuova cartella della tua app e avvia il server di sviluppo:
cd my-twenty-app
yarn twenty dev
--verbose:
yarn twenty dev --verbose
La modalità di sviluppo è disponibile solo sulle istanze di Twenty in esecuzione in modalità sviluppo (NODE_ENV=development). Le istanze di produzione rifiutano le richieste di sincronizzazione in modalità sviluppo. Usa yarn twenty deploy per distribuire sui server di produzione — vedi Pubblicazione delle app per i dettagli. Sincronizzazione una tantum con yarn twenty dev --once
Se non vuoi un watcher in esecuzione in background (ad esempio in una pipeline CI, un hook di Git o un flusso di lavoro scriptato), passa il flag --once. Esegue la stessa pipeline di yarn twenty dev — genera il manifest, effettua il bundling dei file, carica, sincronizza, rigenera il client API tipizzato — ma termina non appena la sincronizzazione è completata:
| Comando | Comportamento | Quando usarlo |
|---|
yarn twenty dev | Monitora i file sorgente e risincronizza a ogni modifica. Rimane in esecuzione finché non lo interrompi. | Sviluppo locale interattivo — vuoi il pannello di stato in tempo reale e un ciclo di feedback immediato. |
yarn twenty dev --once | Esegue una singola build + sincronizzazione, quindi termina con codice 0 in caso di successo o 1 in caso di errore. | Script, CI, hook pre-commit, agenti IA e qualsiasi flusso di lavoro non interattivo. |
Visualizza la tua app in Twenty
Apri http://localhost:2020/settings/applications#developer nel browser. Vai su Settings > Apps e seleziona la scheda Developer. Dovresti vedere la tua app elencata in Your Apps:
Fai clic su My twenty app per aprire la sua registrazione dell’applicazione. Una registrazione è un record a livello di server che descrive la tua app — il suo nome, identificatore univoco, credenziali OAuth e origine (locale, npm o tarball). Risiede sul server, non all’interno di uno spazio di lavoro specifico. Quando installi un’app in uno spazio di lavoro, Twenty crea un’applicazione con ambito dello spazio di lavoro che rimanda a questa registrazione. Una registrazione può essere installata in più spazi di lavoro sullo stesso server.
Fai clic su View installed app per vedere l’app installata. La scheda About mostra la versione corrente e le opzioni di gestione:
Passa alla scheda Content per vedere tutto ciò che la tua app fornisce — oggetti, campi, funzioni logiche e agenti:
È tutto pronto! Modifica qualsiasi file in src/ e le modifiche verranno rilevate automaticamente.
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 | Definisci modelli di dati personalizzati (come Post Card, Invoice) con campi tipizzati |
| Funzioni logiche | Funzioni TypeScript lato server attivate 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 per i tuoi oggetti |
| Layout di pagina | Pagine di dettaglio dei record personalizzate con schede e widget |
Struttura del progetto
Lo scaffolder genera la seguente struttura dei file:
my-twenty-app/
package.json
yarn.lock
.gitignore
.nvmrc
.yarnrc.yml
.oxlintrc.json
tsconfig.json
tsconfig.spec.json # TypeScript config for tests
vitest.config.ts # Vitest test runner configuration
LLMS.md
README.md
.github/
└── workflows/
└── ci.yml # GitHub Actions CI workflow
public/ # Public assets (images, fonts, etc.)
src/
├── application-config.ts # Required — main application configuration
├── default-role.ts # Default role for logic functions
├── constants/
│ └── universal-identifiers.ts # Auto-generated UUIDs and app metadata
└── __tests__/
├── setup-test.ts # Test setup (server health check, config)
└── app-install.integration-test.ts # Integration test
Partire da un esempio
Per iniziare da un esempio più completo con oggetti personalizzati, campi, funzioni logiche, componenti front-end e altro, usa il flag --example:
npx create-twenty-app@latest my-twenty-app --example postcard
yarn twenty add (vedi Creare app).
File principali
| File / Cartella | Scopo |
|---|
package.json | Dichiara il nome, la versione e le dipendenze della tua app. Include uno script twenty così puoi eseguire yarn twenty help per vedere tutti i comandi. |
src/application-config.ts | Obbligatorio. Il file di configurazione principale della tua app. |
src/default-role.ts | Ruolo predefinito che controlla a cosa possono accedere le tue funzioni logiche. |
src/constants/universal-identifiers.ts | UUID generati automaticamente e metadati dell’app (nome visualizzato, descrizione). |
src/__tests__/ | Test di integrazione (setup + test di esempio). |
public/ | Asset statici (immagini, font) serviti insieme alla tua app. |
Server di sviluppo locale
Lo scaffolder ha già avviato per te un server Twenty locale. Per gestirlo in seguito, usa yarn twenty server:
| Comando | Descrizione |
|---|
yarn twenty server start | Avvia il server locale (scarica l’immagine se necessario) |
yarn twenty server start --port 3030 | Avvia su una porta personalizzata |
yarn twenty server start --test | Avvia un’istanza di test separata sulla porta 2021 |
yarn twenty server stop | Arresta il server (conserva i dati) |
yarn twenty server status | Mostra stato del server, URL e credenziali |
yarn twenty server logs | Trasmetti in streaming i log del server |
yarn twenty server logs --lines 100 | Mostra le ultime 100 righe di log |
yarn twenty server reset | Elimina tutti i dati e riparti da zero |
twenty-app-dev-data per PostgreSQL, twenty-app-dev-storage per i file). Usa reset per cancellare tutto e ripartire da zero.
Esecuzione di un’istanza di test
Passa --test a qualsiasi comando server per gestire una seconda istanza completamente isolata — utile per eseguire test di integrazione o per sperimentare senza toccare i tuoi dati di sviluppo principali.
| Comando | Descrizione |
|---|
yarn twenty server start --test | Avvia l’istanza di test (per impostazione predefinita usa la porta 2021) |
yarn twenty server stop --test | Arresta l’istanza di test |
yarn twenty server status --test | Mostra stato, URL e credenziali dell’istanza di test |
yarn twenty server logs --test | Trasmetti in streaming i log dell’istanza di test |
yarn twenty server reset --test | Cancella i dati di test e riparti da zero |
twenty-app-dev-test) con volumi dedicati (twenty-app-dev-test-data, twenty-app-dev-test-storage) e configurazione dedicata, così può essere eseguita in parallelo con la tua istanza principale senza conflitti. Combina --test con --port per sovrascrivere il valore predefinito 2021.
Il server richiede che Docker sia in esecuzione. Se vedi l’errore “Docker not running”, assicurati che Docker Desktop (o il demone Docker) sia avviato.
Configurazione manuale (senza lo scaffolder)
Se preferisci configurare tutto manualmente invece di usare create-twenty-app, puoi farlo in due passaggi.
1. Aggiungi twenty-sdk e twenty-client-sdk come dipendenze:
yarn add twenty-sdk twenty-client-sdk
twenty al tuo package.json:
{
"scripts": {
"twenty": "twenty"
}
}
yarn twenty dev, yarn twenty help e tutti gli altri comandi.
Non installare twenty-sdk globalmente. Usalo sempre come dipendenza locale del progetto, in modo che ogni progetto possa fissare la propria versione.
Risoluzione dei problemi
Se riscontri problemi:
- Assicurati che Docker sia in esecuzione prima di avviare lo strumento di scaffolding con un’istanza locale.
- Assicurati di usare Node.js 24+ (
node -v per verificare).
- Assicurati che Corepack sia abilitato (
corepack enable) in modo che Yarn 4 sia disponibile.
- Prova a eliminare
node_modules ed eseguire di nuovo yarn install se le dipendenze sembrano danneggiate.
Ancora bloccato? Chiedi aiuto su Discord di Twenty.
