Skip to main content
Le app di Twenty sono pacchetti TypeScript che estendono il tuo spazio di lavoro con oggetti personalizzati, logica, componenti dell’interfaccia utente (UI) e funzionalità di IA. Vengono eseguite sulla piattaforma Twenty con sandboxing completo e controlli delle autorizzazioni.

​
Come funzionano le app

Un’app è una raccolta di entità dichiarate utilizzando le funzioni defineEntity() del pacchetto twenty-sdk. L’SDK rileva queste dichiarazioni tramite analisi dell’AST in fase di build e produce un manifest — una descrizione completa di ciò che la tua app aggiunge a uno spazio di lavoro. 
your-app/
├── src/
│   ├── application-config.ts    ← defineApplication (required, one per app)
│   ├── roles/                   ← defineRole
│   ├── objects/                 ← defineObject
│   ├── fields/                  ← defineField
│   ├── logic-functions/         ← defineLogicFunction
│   ├── front-components/        ← defineFrontComponent
│   ├── skills/                  ← defineSkill
│   ├── agents/                  ← defineAgent
│   ├── views/                   ← defineView
│   ├── navigation-menu-items/   ← defineNavigationMenuItem
│   └── page-layouts/            ← definePageLayout
├── public/                      ← Static assets (images, icons)
└── package.json
L’organizzazione dei file dipende da te. Il rilevamento delle entità è basato sull’AST — l’SDK trova le chiamate a export default defineEntity(...) indipendentemente da dove si trova il file. La struttura delle cartelle sopra è una convenzione, non un requisito.

​
Tipi di entità

EntitàScopoDocumentazione
ApplicazioneIdentità dell’app, autorizzazioni, variabiliModello dati
RuoloSet di autorizzazioni per oggetti e campiModello dati
OggettoTabelle di dati personalizzate con campiModello dati
CampoEstendi gli oggetti esistenti, definisci le relazioniModello dati
Funzione logicaTypeScript lato server con triggerFunzioni logiche
Componente front-endUI React in sandbox nella pagina di TwentyComponenti front-end
AbilitàIstruzioni riutilizzabili per agenti IAAbilità e agenti
AgenteAssistenti IA con prompt personalizzatiAbilità e agenti
VistaViste di elenco dei record preconfigurateLayout
Voce del menu di navigazioneVoci della barra laterale personalizzateLayout
Layout di paginaSchede e widget personalizzati nelle pagine dei recordLayout

​
Sandboxing

  • Le funzioni logiche vengono eseguite in processi Node.js isolati sul server. Accedono ai dati solo tramite il client API tipizzato, con ambito limitato alle autorizzazioni del ruolo dell’app.
  • I componenti front-end vengono eseguiti in Web Workers utilizzando il Remote DOM — isolati dalla pagina principale ma renderizzando elementi DOM nativi (non iframe). Comunicano con Twenty tramite un’API host basata sul passaggio di messaggi.
  • Le autorizzazioni vengono applicate a livello di API. Il token di runtime (TWENTY_APP_ACCESS_TOKEN) è derivato dal ruolo definito in defineApplication().

​
Ciclo di vita dell’app

┌─────────────────────────────────────────────────────────┐
│ Development                                             │
│   npx create-twenty-app → yarn twenty dev (live sync)   │
├─────────────────────────────────────────────────────────┤
│ Build & Deploy                                          │
│   yarn twenty build → yarn twenty deploy                │
├─────────────────────────────────────────────────────────┤
│ Install flow                                            │
│   upload → [pre-install] → metadata migration →         │
│   generate SDK → [post-install]                         │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘
  • yarn twenty dev — monitora i file sorgente e sincronizza in tempo reale le modifiche su un server Twenty connesso. Il client API tipizzato viene rigenerato automaticamente quando lo schema cambia.
  • yarn twenty build — compila TypeScript, crea i bundle delle funzioni logiche e dei componenti front-end con esbuild e produce un manifest.
  • Hook di pre/post-installazione — funzioni logiche opzionali che vengono eseguite durante l’installazione. Consulta Funzioni logiche per i dettagli.

​
Prossimi passaggi

Modello dati

Definisci oggetti, campi, ruoli e relazioni.

Funzioni logiche

Funzioni lato server con trigger HTTP, cron ed eventi.

Componenti front-end

Componenti React in sandbox nell’UI di Twenty.

Disposizione

Viste, voci di navigazione e layout delle pagine dei record.

Skill e agenti

Abilità e agenti IA con prompt personalizzati.

CLI e test

Comandi CLI, test, asset, remoti e CI.

Pubblicazione

Distribuisci su un server o pubblica sul marketplace.