Vai al contenuto principale
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. Queste funzioni convalidano la configurazione in fase di build e offrono il completamento automatico nell’IDE e la sicurezza dei tipi. 
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, ruolo predefinito, variabiliConfigurazione dell’applicazione
RuoloSet di autorizzazioni per oggetti e campiRuoli e autorizzazioni
OggettoTipi di record personalizzati con campiOggetti
CampoAggiungi campi agli oggetti di altre appEstensione degli oggetti
RelazioneCollegamenti bidirezionali tra oggettiRelazioni
Funzione logicaTypeScript lato server con triggerFunzioni logiche
AbilitàIstruzioni riutilizzabili per agenti IAAbilità e agenti
AgenteAssistenti IA con prompt personalizzatiAbilità e agenti
Provider di connessioneCredenziali OAuth per API di terze partiConnessioni
VistaViste di elenco dei record preconfigurateViste
Voce del menu di navigazioneVoci della barra laterale personalizzateVoci del menu di navigazione
Layout di paginaSchede e widget nella pagina dei dettagli di un recordLayout di pagina
Componente front-endUI React in sandbox all’interno di TwentyComponenti front-end
Voce del menu comandiAzioni rapide e voci Cmd+KVoci del menu comandi

​
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 dev:build → yarn twenty app:publish        │
├─────────────────────────────────────────────────────────┤
│ 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 dev: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 opzionali che vengono eseguite durante l’installazione. Vedi Hook di installazione per i dettagli.

​
Prossimi passaggi

Configurazione

Identità dell’applicazione, ruolo predefinito e hook di installazione.

Dati

Oggetti, campi e relazioni bidirezionali.

Logica

Funzioni logiche, abilità, agenti e connessioni OAuth.

Layout

Viste, navigazione, layout di pagina, componenti front-end.

Operazioni

CLI, test, remoti, CI e pubblicazione della tua app.