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

Le app ti permettono di estendere Twenty con oggetti, campi, funzioni logiche, competenze IA e componenti UI personalizzati — il tutto gestito come codice.

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

## Passaggio 1: 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.

<Note>
Lo strumento di scaffolding supporta questi flag:

* `--minimal` — genera solo i file essenziali, senza esempi (predefinito)
* `--exhaustive` — genera tutte le entità di esempio
* `--name <name>` — imposta il nome dell'app (salta la richiesta)
* `--display-name <displayName>` — imposta il nome visualizzato (salta la richiesta)
* `--description <description>` — imposta la descrizione (salta la richiesta)
* `--skip-local-instance` — salta la richiesta di configurazione del server locale
</Note>

## Passaggio 2: 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>

## Passaggio 3: 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>

## Passaggio 4: 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>

## Passaggio 5: 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>

## Passaggio 6: 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.

Vai a [Creare app](/l/it/developers/extend/apps/building) per una guida dettagliata sulla creazione di oggetti, funzioni logiche, componenti front-end, skill e altro.

---

## Struttura del progetto

Lo strumento di scaffolding genera la seguente struttura di file (mostrata con la modalità `--exhaustive`, che include esempi per ogni tipo di entità):

```text filename="my-twenty-app/"
my-twenty-app/
  package.json
  yarn.lock
  .gitignore
  .nvmrc
  .yarnrc.yml
  .yarn/
    install-state.gz
  .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
  ├── __tests__/
  │   ├── setup-test.ts                   # Test setup (server health check, config)
  │   └── app-install.integration-test.ts # Example integration test
  ├── 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
  │   ├── create-hello-world-company.ts   # Example logic function using CoreApiClient
  │   ├── pre-install.ts                  # Runs before installation
  │   └── post-install.ts                 # Runs after installation
  ├── front-components/
  │   └── hello-world.tsx                 # Example front component
  ├── page-layouts/
  │   └── example-record-page-layout.ts   # Example page layout with 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
  └── agents/
      └── example-agent.ts                # Example AI agent definition
```

Per impostazione predefinita (`--minimal`), vengono creati solo i file principali: `application-config.ts`, `roles/default-role.ts`, `logic-functions/pre-install.ts` e `logic-functions/post-install.ts`. Usa `--exhaustive` per includere tutti i file di esempio mostrati sopra.

### 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/roles/`                 | Definisce i ruoli che controllano a cosa possono accedere le tue funzioni logiche.                                                                         |
| `src/logic-functions/`       | Funzioni lato server attivate da route, pianificazioni cron o eventi del database.                                                                         |
| `src/front-components/`      | Componenti React che vengono renderizzati all'interno della UI di Twenty.                                                                                  |
| `src/objects/`               | Definizioni di oggetti personalizzati per estendere il tuo modello dati.                                                                                   |
| `src/fields/`                | Campi personalizzati aggiunti a oggetti esistenti.                                                                                                         |
| `src/views/`                 | Configurazioni di viste salvate.                                                                                                                           |
| `src/navigation-menu-items/` | Link personalizzati nella navigazione laterale.                                                                                                            |
| `src/skills/`                | Abilità che estendono gli agenti IA di Twenty.                                                                                                             |
| `src/agents/`                | Agenti IA con prompt personalizzati.                                                                                                                       |
| `src/page-layouts/`          | Layout di pagina personalizzati per le viste dei record.                                                                                                   |
| `src/__tests__/`             | Test di integrazione (setup + test di esempio).                                                                                                            |
| `public/`                    | Asset statici (immagini, font) serviti insieme alla tua app.                                                                                               |

## Gestione dei remoti

Un **remoto** è un server Twenty a cui la tua app si connette. Durante la configurazione, lo strumento di scaffolding ne crea uno automaticamente per te. Puoi aggiungere altri remoti o passare da uno all'altro in qualsiasi momento.

```bash filename="Terminal"
# Add a new remote (opens a browser for OAuth login)
yarn twenty remote add

# Connect to a local Twenty server (auto-detects port 2020 or 3000)
yarn twenty remote add --local

# Add a remote non-interactively (useful for CI)
yarn twenty remote add --api-url https://your-twenty-server.com --api-key $TWENTY_API_KEY --as my-remote

# List all configured remotes
yarn twenty remote list

# Switch the active remote
yarn twenty remote switch <name>
```

Le tue credenziali sono archiviate in `~/.twenty/config.json`.

## Server di sviluppo locale (`yarn twenty server`)

La CLI può gestire un server Twenty locale in esecuzione in Docker. Questo è lo stesso server avviato automaticamente quando crei lo scheletro di un'app con `create-twenty-app`, ma puoi anche gestirlo manualmente.

### Avvio del server

```bash filename="Terminal"
yarn twenty server start
```

Questo scarica l'immagine Docker `twentycrm/twenty-app-dev:latest` (se non è già presente), crea un container chiamato `twenty-app-dev` e lo avvia sulla porta **2020**. La CLI attende che il server superi il controllo di integrità prima di restituire il controllo.

Vengono creati due volumi Docker per mantenere i dati tra i riavvii:

* `twenty-app-dev-data` — database PostgreSQL
* `twenty-app-dev-storage` — archiviazione file

Se la porta 2020 è già in uso, puoi avviare su una porta diversa:

```bash filename="Terminal"
yarn twenty server start --port 3030
```

La CLI configura automaticamente le variabili interne del container `NODE_PORT` e `SERVER_URL` per corrispondere alla porta scelta, in modo che funzioni logiche, OAuth e tutto il resto del networking interno funzionino correttamente.

Una volta avviato, il server viene registrato automaticamente come remoto `local` nella configurazione della CLI.

### Verifica dello stato del server

```bash filename="Terminal"
yarn twenty server status
```

Mostra se il server è in esecuzione, il suo URL e le credenziali di accesso predefinite (`tim@apple.dev` / `tim@apple.dev`).

### Visualizzazione dei log del server

```bash filename="Terminal"
yarn twenty server logs
```

Trasmette in streaming i log del container. Usa `--lines` per controllare quante righe recenti mostrare:

```bash filename="Terminal"
yarn twenty server logs --lines 100
```

### Arresto del server

```bash filename="Terminal"
yarn twenty server stop
```

Arresta il container. I tuoi dati vengono conservati nei volumi Docker — il prossimo `start` riprenderà da dove avevi lasciato.

### Reimpostazione del server

```bash filename="Terminal"
yarn twenty server reset
```

Rimuove il container **e** elimina entrambi i volumi Docker, cancellando tutti i dati. Il prossimo `start` crea un'istanza nuova.

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

### Riferimento ai comandi

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

## CI con GitHub Actions

Lo strumento di scaffolding genera un workflow GitHub Actions pronto all'uso in `.github/workflows/ci.yml`. Esegue automaticamente i test di integrazione a ogni push su `main` e sulle pull request.

Il workflow:

1. Esegue il checkout del tuo codice
2. Avvia un server Twenty temporaneo utilizzando l'azione `twentyhq/twenty/.github/actions/spawn-twenty-docker-image`
3. Installa le dipendenze con `yarn install --immutable`
4. Esegue `yarn test` con `TWENTY_API_URL` e `TWENTY_API_KEY` iniettati dagli output dell'azione

```yaml .github/workflows/ci.yml
name: CI

on:
  push:
    branches:
      - main
  pull_request: {}

env:
  TWENTY_VERSION: latest

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Spawn Twenty instance
        id: twenty
        uses: twentyhq/twenty/.github/actions/spawn-twenty-docker-image@main
        with:
          twenty-version: ${{ env.TWENTY_VERSION }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Enable Corepack
        run: corepack enable

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: '.nvmrc'
          cache: 'yarn'

      - name: Install dependencies
        run: yarn install --immutable

      - name: Run integration tests
        run: yarn test
        env:
          TWENTY_API_URL: ${{ steps.twenty.outputs.server-url }}
          TWENTY_API_KEY: ${{ steps.twenty.outputs.access-token }}
```

Non è necessario configurare alcun secret — l'azione `spawn-twenty-docker-image` avvia un server Twenty effimero direttamente nel runner e fornisce i dettagli di connessione. Il secret `GITHUB_TOKEN` è fornito automaticamente da GitHub.

Per fissare una versione specifica di Twenty invece di `latest`, modifica la variabile d'ambiente `TWENTY_VERSION` all'inizio del workflow.

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