---
title: Per iniziare
description: Crea la tua prima app Twenty in pochi minuti.
---

<Warning>
Le app sono attualmente in fase alfa. La funzionalità funziona ma è ancora in evoluzione.
</Warning>

## 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"
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.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/start-instance.png" alt="Avviare l'istanza locale?" />
</div>

### 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`

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/login.png" alt="Schermata di accesso di Twenty" />
</div>

### 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.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/authorize.png" alt="Schermata di autorizzazione della CLI di Twenty" />
</div>

Una volta autorizzato, il terminale confermerà che tutto è configurato.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/scaffolded.png" alt="App creata con successo" />
</div>

### Inizia a sviluppare

Entra nella nuova cartella della tua app e avvia il server di sviluppo:

```bash filename="Terminal"
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"
yarn twenty dev --verbose
```

<Warning>
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.
</Warning>

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/dev.jpg" alt="Output del terminale in modalità sviluppo" />
</div>

### 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**:

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-1.png" alt="Elenco Your Apps che mostra My twenty app" />
</div>

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.

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-2.png" alt="Dettagli della registrazione dell'applicazione" />
</div>

Fai clic su **View installed app** per vedere l'app installata. La scheda **About** mostra la versione corrente e le opzioni di gestione:

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="App installata — scheda About" />
</div>

Passa alla scheda **Content** per vedere tutto ciò che la tua app fornisce — oggetti, campi, funzioni logiche e agenti:

<div style={{textAlign: 'center'}}>
  <img src="/images/docs/developers/extends/apps/app-in-ui-4.png" alt="App installata — scheda Content" />
</div>

È 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/"
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"
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 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.

<Note>
  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.
</Note>

## 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"
yarn add twenty-sdk twenty-client-sdk
```

**2. Aggiungi uno script `twenty` al tuo `package.json`:**

```json filename="package.json"
{
  "scripts": {
    "twenty": "twenty"
  }
}
```

Ora puoi eseguire `yarn twenty dev`, `yarn twenty help` e tutti gli altri comandi.

<Note>
Non installare `twenty-sdk` globalmente. Usalo sempre come dipendenza locale del progetto, in modo che ogni progetto possa fissare la propria versione.
</Note>

## 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).
