Vai al contenuto principale

​
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.
Avviare l'istanza 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
Schermata di accesso di Twenty

​
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.
App creata con successo

​
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
ComandoComportamentoQuando usarlo
yarn twenty devMonitora 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 --onceEsegue 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:
App installata — scheda About
Passa alla scheda Content per vedere tutto ciò che la tua app fornisce — oggetti, campi, funzioni logiche e agenti:
App installata — scheda Content
È 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 campiDefinisci modelli di dati personalizzati (come Post Card, Invoice) con campi tipizzati
Funzioni logicheFunzioni TypeScript lato server attivate da route HTTP, pianificazioni cron o eventi del database
Componenti front-endComponenti React che vengono renderizzati all’interno dell’UI di Twenty (pannello laterale, widget, menu comandi)
Skill e agentiFunzionalità di IA — istruzioni riutilizzabili e assistenti autonomi
Viste e navigazioneViste elenco preconfigurate e voci di menu della barra laterale per i tuoi oggetti
Layout di paginaPagine 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 / CartellaScopo
package.jsonDichiara 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.tsObbligatorio. Il file di configurazione principale della tua app.
src/default-role.tsRuolo predefinito che controlla a cosa possono accedere le tue funzioni logiche.
src/constants/universal-identifiers.tsUUID 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:
ComandoDescrizione
yarn twenty server startAvvia il server locale (scarica l’immagine se necessario)
yarn twenty server start --port 3030Avvia su una porta personalizzata
yarn twenty server start --testAvvia un’istanza di test separata sulla porta 2021
yarn twenty server stopArresta il server (conserva i dati)
yarn twenty server statusMostra stato del server, URL e credenziali
yarn twenty server logsTrasmetti in streaming i log del server
yarn twenty server logs --lines 100Mostra le ultime 100 righe di log
yarn twenty server resetElimina 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.
ComandoDescrizione
yarn twenty server start --testAvvia l’istanza di test (per impostazione predefinita usa la porta 2021)
yarn twenty server stop --testArresta l’istanza di test
yarn twenty server status --testMostra stato, URL e credenziali dell’istanza di test
yarn twenty server logs --testTrasmetti in streaming i log dell’istanza di test
yarn twenty server reset --testCancella 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.