Per iniziare

• Definisci oggetti e campi personalizzati come codice (modello dati gestito)
• Crea funzioni logiche con trigger personalizzati (route HTTP, cron, eventi del database)
• Definisci le abilità per gli agenti IA
• Crea componenti front-end che vengono renderizzati all’interno della UI di Twenty
• Distribuisci la stessa app su più spazi di lavoro

​

Prerequisiti

• Node.js 24+ e Yarn 4
• Uno spazio di lavoro Twenty e una chiave API (creane una su https://app.twenty.com/settings/api-webhooks)

​

Per iniziare

# Scaffold a new app (includes all examples by default)
npx create-twenty-app@latest my-twenty-app
cd my-twenty-app

# Start dev mode: automatically syncs local changes to your workspace
yarn twenty app:dev

# Default (exhaustive): all examples (object, field, logic function, front component, view, navigation menu item, skill)
npx create-twenty-app@latest my-app

# Minimal: only core files (application-config.ts and default-role.ts)
npx create-twenty-app@latest my-app --minimal

# Add a new entity to your application (guided)
yarn twenty entity:add

# Watch your application's function logs
yarn twenty function:logs

# Execute a function by name
yarn twenty function:execute -n my-function -p '{"name": "test"}'

# Execute the pre-install function
yarn twenty function:execute --preInstall

# Execute the post-install function
yarn twenty function:execute --postInstall

# Uninstall the application from the current workspace
yarn twenty app:uninstall

# Display commands' help
yarn twenty help

​

Struttura del progetto (generata dallo scaffolder)

• Copia un’applicazione base minimale in my-twenty-app/
• Aggiunge una dipendenza locale twenty-sdk e la configurazione di Yarn 4
• Crea file di configurazione e script collegati alla CLI twenty
• Genera i file principali (configurazione dell’applicazione, ruolo predefinito per le funzioni logiche, funzioni di pre-installazione e post-installazione) più i file di esempio in base alla modalità di scaffolding

my-twenty-app/
  package.json
  yarn.lock
  .gitignore
  .nvmrc
  .yarnrc.yml
  .yarn/
    install-state.gz
  .oxlintrc.json
  tsconfig.json
  README.md
  public/                           # Public assets folder (images, fonts, etc.)
  src/
  ├── application-config.ts           # Required - main application configuration
  ├── roles/
  │   └── default-role.ts               # Default role for logic functions
  ├── objects/
  │   └── example-object.ts             # Example custom object definition
  ├── fields/
  │   └── example-field.ts              # Example standalone field definition
  ├── logic-functions/
  │   ├── hello-world.ts                # Example logic function
  │   ├── pre-install.ts                # Pre-install logic function
  │   └── post-install.ts               # Post-install logic function
  ├── front-components/
  │   └── hello-world.tsx               # Example front component
  ├── views/
  │   └── example-view.ts                # Example saved view definition
  ├── navigation-menu-items/
  │   └── example-navigation-menu-item.ts # Example sidebar navigation link
  └── skills/
      └── example-skill.ts                # Example AI agent skill definition

• package.json: Dichiara il nome dell’app, la versione, i motori (Node 24+, Yarn 4) e aggiunge twenty-sdk più uno script twenty che delega alla CLI locale twenty. Esegui yarn twenty help per elencare tutti i comandi disponibili.
• .gitignore: Ignora i file generati comuni come node_modules, .yarn, generated/ (client tipizzato), dist/, build/, cartelle di coverage, file di log e file .env*.
• yarn.lock, .yarnrc.yml, .yarn/: Bloccano e configurano la toolchain Yarn 4 utilizzata dal progetto.
• .nvmrc: Fissa la versione di Node.js prevista dal progetto.
• .oxlintrc.json e tsconfig.json: Forniscono linting e configurazione TypeScript per i sorgenti TypeScript della tua app.
• README.md: Un breve README nella radice dell’app con istruzioni di base.
• public/: Una cartella per archiviare risorse pubbliche (immagini, font, file statici) che saranno servite con la tua applicazione. I file collocati qui vengono caricati durante la sincronizzazione e sono accessibili in fase di esecuzione.
• src/: Il luogo principale in cui definisci la tua applicazione come codice

​

Rilevamento delle entità

// This file can be named anything and placed anywhere in src/
import { defineObject, FieldType } from 'twenty-sdk';

export default defineObject({
  universalIdentifier: '...',
  nameSingular: 'postCard',
  // ... rest of config
});

• yarn twenty app:dev genererà automaticamente due client API tipizzati in node_modules/twenty-sdk/generated: CoreApiClient (per i dati dell’area di lavoro tramite /graphql) e MetadataApiClient (per la configurazione dell’area di lavoro e il caricamento di file tramite /metadata).
• yarn twenty entity:add aggiungerà file di definizione delle entità sotto src/ per i tuoi oggetti, funzioni, componenti front-end, ruoli, competenze e altro ancora.

​

Autenticazione

• URL dell’API (predefinito a http://localhost:3000 o al profilo dello spazio di lavoro corrente)
• Chiave API

​

Gestione delle aree di lavoro

# Login interactively (recommended)
yarn twenty auth:login

# Login to a specific workspace profile
yarn twenty auth:login --workspace my-custom-workspace

# List all configured workspaces
yarn twenty auth:list

# Switch the default workspace (interactive)
yarn twenty auth:switch

# Switch to a specific workspace
yarn twenty auth:switch production

# Check current authentication status
yarn twenty auth:status

​

Configurazione manuale (senza lo scaffolder)

yarn add -D twenty-sdk

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

​

Risoluzione dei problemi

• Errori di autenticazione: esegui yarn twenty auth:login e assicurati che la tua chiave API abbia i permessi richiesti.
• Impossibile connettersi al server: verifica l’URL dell’API e che il server Twenty sia raggiungibile.
• Tipi o client mancanti/obsoleti: riavvia yarn twenty app:dev — genera automaticamente il client tipizzato.
• Modalità di sviluppo non sincronizzata: assicurati che yarn twenty app:dev sia in esecuzione e che le modifiche non vengano ignorate dal tuo ambiente.