github-actions[bot]
0b8421a45a
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
256 lines
13 KiB
Plaintext
256 lines
13 KiB
Plaintext
---
|
|
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.
|
|
|
|
## Create your first app
|
|
|
|
### Scaffold your 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.
|
|
|
|
### Set up a local Twenty instance
|
|
|
|
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>
|
|
|
|
### Sign in to your workspace
|
|
|
|
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>
|
|
|
|
### Authorize the 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>
|
|
|
|
### Start developing
|
|
|
|
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>
|
|
|
|
### See your 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
|
|
|
|
Apps are composed of **entities** — each defined as a TypeScript file with a single `export default`:
|
|
|
|
| Entity | What it does |
|
|
| ------------------------ | --------------------------------------------------------------------------------------------- |
|
|
| **Objects & Fields** | Define custom data models (like Post Card, Invoice) with typed fields |
|
|
| **Funzioni logiche** | Server-side TypeScript functions triggered by HTTP routes, cron schedules, or database events |
|
|
| **Componenti front-end** | React components that render inside Twenty's UI (side panel, widgets, command menu) |
|
|
| **Skills & Agents** | AI capabilities — reusable instructions and autonomous assistants |
|
|
| **Views & Navigation** | Pre-configured list views and sidebar menu items for your objects |
|
|
| **Layout di pagina** | Custom record detail pages with tabs and widgets |
|
|
|
|
Head over to [Building Apps](/l/it/developers/extend/apps/building) for a detailed guide on each entity type.
|
|
|
|
---
|
|
|
|
## Struttura del progetto
|
|
|
|
The scaffolder generates the following file structure:
|
|
|
|
```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
|
|
```
|
|
|
|
### Starting from an example
|
|
|
|
To start from a more complete example with custom objects, fields, logic functions, front components, and more, use the `--example` flag:
|
|
|
|
```bash filename="Terminal"
|
|
npx create-twenty-app@latest my-twenty-app --example postcard
|
|
```
|
|
|
|
Examples are sourced from the [twenty-apps/examples](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/examples) directory on GitHub. You can also scaffold individual entities into an existing project with `yarn twenty add` (see [Building Apps](/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` | Default role that controls what your logic functions can access. |
|
|
| `src/constants/universal-identifiers.ts` | Auto-generated UUIDs and app metadata (display name, description). |
|
|
| `src/__tests__/` | Test di integrazione (setup + test di esempio). |
|
|
| `public/` | Asset statici (immagini, font) serviti insieme alla tua app. |
|
|
|
|
## Local development server
|
|
|
|
The scaffolder already started a local Twenty server for you. To manage it later, use `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 |
|
|
|
|
Data is persisted across restarts in two Docker volumes (`twenty-app-dev-data` for PostgreSQL, `twenty-app-dev-storage` for files). Use `reset` to wipe everything and start fresh.
|
|
|
|
<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).
|