Per iniziare

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

Ti verrà chiesto di inserire un nome e una descrizione per la tua app. Premi Invio per accettare i valori predefiniti. Questo crea una nuova cartella chiamata 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.

Schermata di autorizzazione della CLI di Twenty

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

Questo controlla i file sorgente, ricompila a ogni modifica e sincronizza automaticamente la tua app con il server Twenty locale. Dovresti vedere un pannello di stato in tempo reale nel terminale. Per un output più dettagliato (log di build, richieste di sincronizzazione, tracce di errore), usa il flag --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.

Output del terminale in modalità sviluppo

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:

yarn twenty dev --once

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.

Entrambe le modalità richiedono un server Twenty in esecuzione in modalità di sviluppo e un remote autenticato — si applicano gli stessi prerequisiti.

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:

Elenco Your Apps che mostra My twenty app

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.

Dettagli della registrazione dell'applicazione

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

Vai a Creare app per una guida dettagliata su ogni tipo di entità.

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

Gli esempi provengono dalla directory twenty-apps/examples su GitHub. Puoi anche aggiungere singole entità a un progetto esistente con 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

I dati vengono mantenuti tra i riavvii in due volumi Docker (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

L’istanza di test viene eseguita nel proprio container Docker (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

2. Aggiungi uno script twenty al tuo package.json:

{
  "scripts": {
    "twenty": "twenty"
  }
}

Ora puoi eseguire 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.

Panoramica

App

API

Auto-ospitazione

Contribuire

Cosa sono le app?

Prerequisiti

Crea la tua prima app

Crea lo scheletro della tua app

Configura un’istanza locale di Twenty

Accedi al tuo spazio di lavoro

Autorizza l’app

Inizia a sviluppare

Sincronizzazione una tantum con `yarn twenty dev --once`

Visualizza la tua app in Twenty

Cosa puoi creare

Struttura del progetto

Partire da un esempio

File principali

Server di sviluppo locale

Esecuzione di un’istanza di test

Configurazione manuale (senza lo scaffolder)

Risoluzione dei problemi

​Cosa sono le app?

​Prerequisiti

​Crea la tua prima app

​Crea lo scheletro della tua app

​Configura un’istanza locale di Twenty

​Accedi al tuo spazio di lavoro

​Autorizza l’app

​Inizia a sviluppare

​Sincronizzazione una tantum con yarn twenty dev --once

​Visualizza la tua app in Twenty

​Cosa puoi creare

​Struttura del progetto

​Partire da un esempio

​File principali

​Server di sviluppo locale

​Esecuzione di un’istanza di test

​Configurazione manuale (senza lo scaffolder)

​Risoluzione dei problemi

Cosa sono le app?

Prerequisiti

Crea la tua prima app

Crea lo scheletro della tua app

Configura un’istanza locale di Twenty

Accedi al tuo spazio di lavoro

Autorizza l’app

Inizia a sviluppare

Sincronizzazione una tantum con `yarn twenty dev --once`

Visualizza la tua app in Twenty

Cosa puoi creare

Struttura del progetto

Partire da un esempio

File principali

Server di sviluppo locale

Esecuzione di un’istanza di test

Configurazione manuale (senza lo scaffolder)

Risoluzione dei problemi