> ## Documentation Index > Fetch the complete documentation index at: https://docs.get-clara.tech/llms.txt > Use this file to discover all available pages before exploring further. # Per iniziare > Crea la tua prima app Twenty in pochi minuti. ## 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](https://nodejs.org/) * **Yarn 4** — Incluso con Node.js tramite Corepack. Abilitalo eseguendo `corepack enable` * **Docker** — [Scarica qui](https://www.docker.com/products/docker-desktop/). 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: ```bash filename="Terminal" theme={null} 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: ```bash filename="Terminal" theme={null} 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`: ```bash filename="Terminal" theme={null} 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](/l/it/developers/extend/apps/publishing) 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**: ```bash filename="Terminal" theme={null} 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](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](/l/it/developers/extend/apps/building) per una guida dettagliata su ogni tipo di entità. *** ## Struttura del progetto Lo scaffolder genera la seguente struttura dei file: ```text filename="my-twenty-app/" theme={null} 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`: ```bash filename="Terminal" theme={null} npx create-twenty-app@latest my-twenty-app --example postcard ``` Gli esempi provengono dalla directory [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) su GitHub. Puoi anche aggiungere singole entità a un progetto esistente con `yarn twenty add` (vedi [Creare app](/l/it/developers/extend/apps/building#scaffolding-entities-with-yarn-twenty-add)). ### 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:** ```bash filename="Terminal" theme={null} yarn add twenty-sdk twenty-client-sdk ``` **2. Aggiungi uno script `twenty` al tuo `package.json`:** ```json filename="package.json" theme={null} { "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](https://discord.com/channels/1130383047699738754/1130386664812982322).