i18n - docs translations (#21789)
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
This commit is contained in:
github-actions[bot]
committed by
GitHub
GitHub
parent
22baf2c6c5
commit
2b3b2362db
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: Concetti
|
||||
description: Come funzionano le app Twenty — modello di entità, sandboxing e ciclo di vita dell’installazione.
|
||||
icon: sitemap
|
||||
---
|
||||
|
||||
Le app di Twenty sono pacchetti TypeScript che estendono il tuo spazio di lavoro con oggetti personalizzati, logica, componenti dell'interfaccia utente (UI) e funzionalità di IA. Vengono eseguite sulla piattaforma Twenty con sandboxing completo e controlli delle autorizzazioni.
|
||||
|
||||
## Come funzionano le app
|
||||
|
||||
Un'app è una raccolta di **entità** dichiarate utilizzando le funzioni `defineEntity()` del pacchetto `twenty-sdk`. L'SDK rileva queste dichiarazioni tramite analisi dell'AST in fase di build e produce un **manifest** — una descrizione completa di ciò che la tua app aggiunge a uno spazio di lavoro. Queste funzioni convalidano la configurazione in fase di build e offrono il completamento automatico nell'IDE e la sicurezza dei tipi.
|
||||
|
||||
```
|
||||
your-app/
|
||||
├── src/
|
||||
│ ├── application-config.ts ← defineApplication (required, one per app)
|
||||
│ ├── roles/ ← defineRole
|
||||
│ ├── objects/ ← defineObject
|
||||
│ ├── fields/ ← defineField
|
||||
│ ├── logic-functions/ ← defineLogicFunction
|
||||
│ ├── front-components/ ← defineFrontComponent
|
||||
│ ├── skills/ ← defineSkill
|
||||
│ ├── agents/ ← defineAgent
|
||||
│ ├── views/ ← defineView
|
||||
│ ├── navigation-menu-items/ ← defineNavigationMenuItem
|
||||
│ └── page-layouts/ ← definePageLayout
|
||||
├── public/ ← Static assets (images, icons)
|
||||
└── package.json
|
||||
```
|
||||
|
||||
<Note>
|
||||
**L'organizzazione dei file dipende da te.** Il rilevamento delle entità è basato sull'AST — l'SDK trova le chiamate a `export default defineEntity(...)` indipendentemente da dove si trova il file. La struttura delle cartelle sopra è una convenzione, non un requisito.
|
||||
</Note>
|
||||
|
||||
## Tipi di entità
|
||||
|
||||
| Entità | Scopo | Documentazione |
|
||||
| -------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------ |
|
||||
| **Applicazione** | Identità dell’app, ruolo predefinito, variabili | [Configurazione dell’applicazione](/l/it/developers/extend/apps/config/application) |
|
||||
| **Ruolo** | Set di autorizzazioni per oggetti e campi | [Ruoli e autorizzazioni](/l/it/developers/extend/apps/config/roles) |
|
||||
| **Oggetto** | Tipi di record personalizzati con campi | [Oggetti](/l/it/developers/extend/apps/data/objects) |
|
||||
| **Campo** | Aggiungi campi agli oggetti di altre app | [Estensione degli oggetti](/l/it/developers/extend/apps/data/extending-objects) |
|
||||
| **Relazione** | Collegamenti bidirezionali tra oggetti | [Relazioni](/l/it/developers/extend/apps/data/relations) |
|
||||
| **Funzione logica** | TypeScript lato server con trigger | [Funzioni logiche](/l/it/developers/extend/apps/logic/logic-functions) |
|
||||
| **Abilità** | Istruzioni riutilizzabili per agenti IA | [Abilità e agenti](/l/it/developers/extend/apps/logic/skills-and-agents) |
|
||||
| **Agente** | Assistenti IA con prompt personalizzati | [Abilità e agenti](/l/it/developers/extend/apps/logic/skills-and-agents) |
|
||||
| **Provider di connessione** | Credenziali OAuth per API di terze parti | [Connessioni](/l/it/developers/extend/apps/logic/connections) |
|
||||
| **Vista** | Viste di elenco dei record preconfigurate | [Viste](/l/it/developers/extend/apps/layout/views) |
|
||||
| **Voce del menu di navigazione** | Voci della barra laterale personalizzate | [Voci del menu di navigazione](/l/it/developers/extend/apps/layout/navigation-menu-items) |
|
||||
| **Layout di pagina** | Schede e widget nella pagina dei dettagli di un record | [Layout di pagina](/l/it/developers/extend/apps/layout/page-layouts) |
|
||||
| **Componente front-end** | UI React in sandbox all’interno di Twenty | [Componenti front-end](/l/it/developers/extend/apps/layout/front-components) |
|
||||
| **Voce del menu comandi** | Azioni rapide e voci Cmd+K | [Voci del menu comandi](/l/it/developers/extend/apps/layout/command-menu-items) |
|
||||
|
||||
## Sandboxing
|
||||
|
||||
* **Le funzioni logiche** vengono eseguite in processi Node.js isolati sul server. Accedono ai dati solo tramite il client API tipizzato, con ambito limitato alle autorizzazioni del ruolo dell'app.
|
||||
* **I componenti front-end** vengono eseguiti in Web Workers utilizzando il Remote DOM — isolati dalla pagina principale ma renderizzando elementi DOM nativi (non iframe). Comunicano con Twenty tramite un'API host basata sul passaggio di messaggi.
|
||||
* **Le autorizzazioni** vengono applicate a livello di API. Il token di runtime (`TWENTY_APP_ACCESS_TOKEN`) è derivato dal ruolo definito in `defineApplication()`.
|
||||
|
||||
## Ciclo di vita dell'app
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Development │
|
||||
│ npx create-twenty-app → yarn twenty dev (live sync) │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ Build & Deploy │
|
||||
│ yarn twenty dev:build → yarn twenty app:publish │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ Install flow │
|
||||
│ upload → [pre-install] → metadata migration → │
|
||||
│ generate SDK → [post-install] │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ Publish │
|
||||
│ npm publish → appears in Twenty marketplace │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
* **`yarn twenty dev`** — monitora i file sorgente e sincronizza in tempo reale le modifiche su un server Twenty connesso. Il client API tipizzato viene rigenerato automaticamente quando lo schema cambia.
|
||||
* **`yarn twenty dev:build`** — compila TypeScript, crea i bundle delle funzioni logiche e dei componenti front-end con esbuild e produce un manifest.
|
||||
* **Hook di pre/post-installazione** — funzioni opzionali che vengono eseguite durante l’installazione. Vedi [Hook di installazione](/l/it/developers/extend/apps/config/install-hooks) per i dettagli.
|
||||
|
||||
## Prossimi passaggi
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Configurazione" icon="screwdriver-wrench" href="/l/it/developers/extend/apps/config/overview">
|
||||
Identità dell’applicazione, ruolo predefinito e hook di installazione.
|
||||
</Card>
|
||||
<Card title="Dati" icon="database" href="/l/it/developers/extend/apps/data/overview">
|
||||
Oggetti, campi e relazioni bidirezionali.
|
||||
</Card>
|
||||
<Card title="Logica" icon="bolt" href="/l/it/developers/extend/apps/logic/overview">
|
||||
Funzioni logiche, abilità, agenti e connessioni OAuth.
|
||||
</Card>
|
||||
<Card title="Layout" icon="table-columns" href="/l/it/developers/extend/apps/layout/overview">
|
||||
Viste, navigazione, layout di pagina, componenti front-end.
|
||||
</Card>
|
||||
<Card title="Operazioni" icon="rocket" href="/l/it/developers/extend/apps/operations/overview">
|
||||
CLI, test, remoti, CI e pubblicazione della tua app.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
title: Server locale
|
||||
description: Gestisci il server Docker Twenty locale — avvia, arresta, aggiorna, istanza di test parallela e configurazione manuale dell'SDK.
|
||||
icon: server
|
||||
---
|
||||
|
||||
## Gestire il server locale
|
||||
|
||||
Usa `yarn twenty docker:*` per controllare il container Twenty locale:
|
||||
|
||||
| Comando | Cosa fa |
|
||||
| -------------------------------------- | -------------------------------------------------- |
|
||||
| `yarn twenty docker:start` | Avvia il server (scarica l'immagine se necessario) |
|
||||
| `yarn twenty docker:start 2.2.0` | Avvia una versione specifica del server |
|
||||
| `yarn twenty docker:start --port 3030` | Avvia su una porta personalizzata |
|
||||
| `yarn twenty docker:stop` | Arresta il server (conserva i dati) |
|
||||
| `yarn twenty docker:status` | Mostra URL, versione e credenziali di accesso |
|
||||
| `yarn twenty docker:logs` | Trasmetti in streaming i log del server |
|
||||
| `yarn twenty docker:reset` | Cancella i dati e riparti da zero |
|
||||
| `yarn twenty docker:upgrade` | Scarica l'ultima immagine `twenty-app-dev` |
|
||||
| `yarn twenty docker:upgrade 2.2.0` | Aggiorna a una versione specifica |
|
||||
|
||||
I dati persistono 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.
|
||||
|
||||
## Blocco della versione del server
|
||||
|
||||
Quando non viene passata alcuna versione, `docker:start` risolve la versione dall'intervallo `engines.twenty` della tua app in `package.json`, lo stesso intervallo rispetto al quale il server effettua la convalida quando la tua app viene installata. Avvia l'immagine `twenty-app-dev` più recente pubblicata che soddisfa l'intervallo, ricorrendo a `latest` quando il campo è assente o nessuna versione pubblicata corrisponde:
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
"engines": {
|
||||
"twenty": ">=2.2.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Passa esplicitamente una versione per ignorare l'intervallo per una singola esecuzione: `yarn twenty docker:start 2.3.0`. Se un container esiste già con una versione diversa, `docker:start` lo aggiorna sul posto (ricreando il container ma preservando i volumi dei tuoi dati).
|
||||
|
||||
## Aggiornamento dell'immagine del server
|
||||
|
||||
`yarn twenty docker:upgrade` scarica l'ultima immagine, confronta i digest e ricrea il container solo se è cambiato qualcosa. I volumi vengono preservati — viene sostituito solo il container. Se è stata scaricata una nuova immagine e il container era in esecuzione, l'upgrade avvia automaticamente un nuovo container; esegui poi `yarn twenty docker:start` per attendere che diventi operativo.
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty docker:upgrade # Latest
|
||||
yarn twenty docker:upgrade 2.2.0 # Specific version
|
||||
```
|
||||
|
||||
Verifica la versione in esecuzione con `yarn twenty docker:status` (mostra `APP_VERSION` incorporata nel container).
|
||||
|
||||
## Esecuzione di un'istanza di test parallela
|
||||
|
||||
Passa `--test` a qualsiasi comando `docker:*` per gestire una seconda istanza completamente isolata — utile per test di integrazione o per sperimentare senza toccare i tuoi dati di sviluppo principali:
|
||||
|
||||
| Comando | Cosa fa |
|
||||
| ----------------------------------- | ------------------------------------------------------------------------ |
|
||||
| `yarn twenty docker:start --test` | Avvia l'istanza di test (per impostazione predefinita usa la porta 2021) |
|
||||
| `yarn twenty docker:stop --test` | Arrestala |
|
||||
| `yarn twenty docker:status --test` | Mostra il suo stato |
|
||||
| `yarn twenty docker:logs --test` | Trasmetti in streaming i suoi log |
|
||||
| `yarn twenty docker:reset --test` | Cancella i suoi dati |
|
||||
| `yarn twenty docker:upgrade --test` | Aggiorna la sua immagine |
|
||||
|
||||
L'istanza di test ha il proprio container (`twenty-app-dev-test`), i propri volumi (`twenty-app-dev-test-data`, `twenty-app-dev-test-storage`) e la propria configurazione — viene eseguita insieme alla tua istanza principale senza conflitti. Combina `--test` con `--port` per sovrascrivere 2021.
|
||||
|
||||
## Configurazione manuale (senza lo scaffolder)
|
||||
|
||||
Salta lo strumento di scaffolding se stai aggiungendo l'SDK a un progetto esistente:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn add twenty-sdk twenty-client-sdk
|
||||
```
|
||||
|
||||
Aggiungi lo script a `package.json`:
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
"scripts": {
|
||||
"twenty": "twenty"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Ora puoi eseguire `yarn twenty dev`, `yarn twenty docker:start` e il resto.
|
||||
|
||||
<Note>
|
||||
Non installare `twenty-sdk` globalmente — bloccalo per progetto in modo che ogni app usi la propria versione.
|
||||
</Note>
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: Struttura del progetto
|
||||
description: Cosa contiene un'app Twenty creata con lo scaffold — file, cartelle e cosa fa ognuno di essi.
|
||||
icon: folder-tree
|
||||
---
|
||||
|
||||
Una nuova app generata da `npx create-twenty-app` si presenta così:
|
||||
|
||||
```text filename="my-twenty-app/"
|
||||
my-twenty-app/
|
||||
package.json
|
||||
src/
|
||||
application-config.ts # Required — your app's entry point
|
||||
default-role.ts # Permissions for logic functions
|
||||
constants/
|
||||
universal-identifiers.ts # Auto-generated UUIDs and metadata
|
||||
__tests__/
|
||||
setup-test.ts
|
||||
app-install.integration-test.ts
|
||||
.github/workflows/ci.yml # GitHub Actions
|
||||
public/ # Static assets
|
||||
vitest.config.ts # Test runner config
|
||||
tsconfig.json, tsconfig.spec.json
|
||||
.nvmrc, .yarnrc.yml, .oxlintrc.json
|
||||
README.md, LLMS.md
|
||||
```
|
||||
|
||||
## File principali
|
||||
|
||||
| File / Cartella | Scopo |
|
||||
| ---------------------------------------- | -------------------------------------------------------------------------------- |
|
||||
| `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 (nome visualizzato, descrizione). |
|
||||
| `src/__tests__/` | Test di integrazione (setup + test di esempio). |
|
||||
| `public/` | Asset statici (immagini, font) serviti insieme alla tua app. |
|
||||
|
||||
<Note>
|
||||
**L'organizzazione dei file dipende da te.** Le cartelle sopra sono convenzioni — l'SDK rileva le entità tramite analisi AST sulle chiamate a `export default defineEntity(...)` indipendentemente da dove si trova il file.
|
||||
</Note>
|
||||
|
||||
## Dipendenze
|
||||
|
||||
Entrambi i pacchetti Twenty SDK devono essere inseriti sotto `devDependencies`, non sotto `dependencies`:
|
||||
|
||||
```json filename="package.json"
|
||||
{
|
||||
"dependencies": {},
|
||||
"devDependencies": {
|
||||
"twenty-client-sdk": "^2.13.0",
|
||||
"twenty-sdk": "^2.13.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
* **`twenty-sdk`** fornisce la CLI `twenty` e gli strumenti di build/scaffolding. Viene eseguito solo in fase di sviluppo e di build e non viene mai importato dal runtime dell'app pubblicata.
|
||||
* **`twenty-client-sdk`** *viene* importato dal codice della tua app (`CoreApiClient`, `MetadataApiClient`, `RestApiClient`), ma Twenty lo fornisce a runtime: le funzioni di logica lo ricevono da un layer SDK generato e i componenti di front-end lo risolvono da moduli forniti dal server. La copia installata viene utilizzata solo per il type checking e per la build al momento del deploy, quindi non è mai necessario includerla nel bundle distribuito.
|
||||
|
||||
Mantenere uno qualsiasi dei pacchetti sotto `dependencies` lo inserisce nel bundle di runtime dell'app installata, dove rappresenta solo zavorra. `twenty build` emette un avviso quando uno dei due è ancora elencato sotto `dependencies`.
|
||||
|
||||
Aggiungi come di consueto le dipendenze di runtime proprie della tua app (librerie che le tue funzioni di logica importano effettivamente a runtime) sotto `dependencies`.
|
||||
@@ -0,0 +1,176 @@
|
||||
---
|
||||
title: Avvio rapido
|
||||
icon: rocket
|
||||
description: Crea la tua prima app Twenty in pochi minuti.
|
||||
---
|
||||
|
||||
## Prerequisiti
|
||||
|
||||
* **Node.js 24+** — [Scarica](https://nodejs.org/)
|
||||
* **Yarn 4** — incluso con Node.js tramite Corepack. Abilitalo: `corepack enable`
|
||||
* **Docker** — [Scarica](https://www.docker.com/products/docker-desktop/). Necessario per eseguire un server Twenty locale. Salta se hai già Twenty in esecuzione altrove.
|
||||
|
||||
La creazione di un'app Twenty ha tre fasi. Lo strumento di scaffolding le combina in un unico comando per il percorso ottimale, ma ogni fase è un concetto distinto — quando qualcosa fallisce, sapere in quale fase ti trovi indica cosa correggere.
|
||||
|
||||
| Fase | Cosa fai | Strumento | Risultato |
|
||||
| ----------------------- | ------------------------------------------------------ | ----------------------------- | ---------------------------------- |
|
||||
| **1. Crea struttura** | Genera il codice sorgente dell'app | `npx create-twenty-app` | Un progetto TypeScript sul disco |
|
||||
| **2. Esegui un server** | Avvia un server Twenty con cui sincronizzare | Docker + `yarn twenty server` | Un'istanza Twenty in esecuzione |
|
||||
| **3. Sincronizza** | Sincronizza in tempo reale il tuo codice con il server | `yarn twenty dev` | Le tue modifiche compaiono nell'UI |
|
||||
|
||||
---
|
||||
|
||||
## Fase 1 — Crea la struttura del progetto
|
||||
|
||||
Crea una nuova app dal modello:
|
||||
|
||||
```bash filename="Terminal"
|
||||
npx create-twenty-app@latest my-twenty-app
|
||||
```
|
||||
|
||||
Ti verrà chiesto un nome e una descrizione — premi **Invio** per usare i valori predefiniti. Questo genera un progetto TypeScript in `my-twenty-app/` con un `application-config.ts` iniziale, un ruolo predefinito, un workflow CI e un test di integrazione.
|
||||
|
||||
**Dopo questa fase:** hai il codice sorgente dell'app sulla tua macchina. Non è ancora in esecuzione — questa è la Fase 2.
|
||||
|
||||
---
|
||||
|
||||
## Fase 2 — Esegui un server Twenty locale
|
||||
|
||||
La tua app ha bisogno di un server Twenty con cui sincronizzarsi. Il server è un'istanza Twenty completa — UI, API GraphQL, PostgreSQL — in esecuzione in locale su Docker. Il tuo codice locale carica le sue definizioni su quel server, che le rende visibili nell'UI.
|
||||
|
||||
Lo strumento di scaffolding ti propone di avviarne uno per te:
|
||||
|
||||
> **Vuoi configurare un'istanza locale di Twenty?**
|
||||
|
||||
* **Sì (consigliato)** — scarica l'immagine Docker `twentycrm/twenty-app-dev` e la avvia sulla porta `2020`. Assicurati prima che Docker sia in esecuzione.
|
||||
* **No** — scegli questa opzione se hai già un server Twenty a cui vuoi connetterti. Puoi collegarlo in seguito con `yarn twenty remote:add`.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/start-instance.png" alt="Avviare l'istanza locale?" />
|
||||
</div>
|
||||
|
||||
Quando il server è attivo, si apre il browser per l'accesso. Usa 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>
|
||||
|
||||
Fai clic su **Authorize** nella schermata successiva — questo concede alla CLI l'accesso al tuo spazio di lavoro.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/authorize.png" alt="Schermata di autorizzazione della CLI di Twenty" />
|
||||
</div>
|
||||
|
||||
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>
|
||||
|
||||
**Dopo questa fase:** hai un server Twenty in esecuzione su [http://localhost:2020](http://localhost:2020) con la tua CLI autorizzata a sincronizzarsi con esso.
|
||||
|
||||
<Note>
|
||||
Se Docker non è installato o in esecuzione, lo strumento di scaffolding ti indicherà il comando di avvio corretto per il tuo sistema operativo. Quando Docker è attivo, puoi riprendere con `yarn twenty docker:start` — non è necessario rifare lo scaffolding.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Fase 3 — Sincronizza le tue modifiche
|
||||
|
||||
Questo è il ciclo interno in cui passerai la maggior parte del tempo.
|
||||
|
||||
```bash filename="Terminal"
|
||||
cd my-twenty-app
|
||||
yarn twenty dev
|
||||
```
|
||||
|
||||
Questo osserva `src/`, ricompila a ogni modifica e sincronizza il risultato con il server. Modifica un file, salvalo e in pochi secondi il server riflette la modifica. Vedrai un pannello di stato in tempo reale nel terminale.
|
||||
|
||||
Per un output più dettagliato (log di build, richieste di sincronizzazione, tracce di errore), aggiungi `--verbose`.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/dev.png" alt="Output del terminale in modalità sviluppo" />
|
||||
</div>
|
||||
|
||||
Apri [http://localhost:2020/settings/applications#developer](http://localhost:2020/settings/applications#developer). Dovresti vedere la tua app sotto **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 vedere la sua **registrazione dell'applicazione** — un record a livello di server che descrive la tua app (nome, identificatore, credenziali OAuth, origine). 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'installazione nello spazio di lavoro. La scheda **About** mostra la versione e le opzioni di gestione.
|
||||
|
||||
<div style={{textAlign: 'center'}}>
|
||||
<img src="/images/docs/developers/extends/apps/app-in-ui-3.png" alt="App installata" />
|
||||
</div>
|
||||
|
||||
**Dopo questa fase:** hai un ciclo di sviluppo in tempo reale. Modifica qualsiasi file in `src/` e compare nell'UI.
|
||||
|
||||
### Sincronizzazione una tantum per CI e script
|
||||
|
||||
Passa `--once` per eseguire una singola build + sincronizzazione ed uscire — stessa pipeline, nessun watcher:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty dev --once
|
||||
```
|
||||
|
||||
| Comando | Comportamento | Quando usarlo |
|
||||
| ---------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||||
| `yarn twenty dev` | Monitora e risincronizza a ogni modifica. Rimane in esecuzione finché non lo interrompi. | Sviluppo locale interattivo. |
|
||||
| `yarn twenty dev --once` | Singola build + sincronizzazione, termina con codice `0` in caso di successo, `1` in caso di errore. | CI, hook pre-commit, agenti IA, flussi di lavoro scriptati. |
|
||||
| `yarn twenty dev --once --dry-run` | Crea e stampa le modifiche ai metadati **senza applicarle**. | Ispezionare quali modifiche verrebbero apportate da una sincronizzazione prima di confermarla. |
|
||||
|
||||
Entrambe le modalità richiedono un remoto autenticato. Vedi [Sincronizzazione e ripristino](/l/it/developers/extend/apps/operations/sync-and-recovery#previewing-changes-dry-run) per maggiori informazioni su `--dry-run`.
|
||||
|
||||
### Opzioni della modalità di sviluppo
|
||||
|
||||
| Opzione | Descrizione |
|
||||
| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| `--once` | Esegui una build e una sincronizzazione una sola volta, quindi esci. |
|
||||
| `--dry-run` | Con `--once`, visualizza in anteprima le modifiche ai metadati senza applicarle. Non scrive nulla. |
|
||||
| `--debounceMs \<ms>` | Imposta il ritardo di debounce delle modifiche ai file in millisecondi (predefinito: `2000`). |
|
||||
| `--verbose` / `--debug` | Mostra log di build dettagliati, richieste di sincronizzazione e tracce di errore. |
|
||||
|
||||
## 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** | Modelli di dati personalizzati (Cartolina, Fattura, ecc.) con campi tipizzati |
|
||||
| **Funzioni logiche** | TypeScript lato server attivato 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 |
|
||||
| **Layout di pagina** | Pagine di dettaglio dei record personalizzate con schede e widget |
|
||||
|
||||
Riferimento completo: [Concetti](/l/it/developers/extend/apps/getting-started/concepts).
|
||||
|
||||
## Prossimi passaggi
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Configurazione" icon="screwdriver-wrench" href="/l/it/developers/extend/apps/config/overview">
|
||||
Identità dell'applicazione, ruolo predefinito, hook di installazione, asset pubblici.
|
||||
</Card>
|
||||
<Card title="Dati" icon="database" href="/l/it/developers/extend/apps/data/overview">
|
||||
Oggetti, campi e relazioni bidirezionali.
|
||||
</Card>
|
||||
<Card title="Logica" icon="bolt" href="/l/it/developers/extend/apps/logic/overview">
|
||||
Funzioni logiche, skill, agenti e connessioni OAuth.
|
||||
</Card>
|
||||
<Card title="Layout" icon="table-columns" href="/l/it/developers/extend/apps/layout/overview">
|
||||
Viste, navigazione, layout di pagina, componenti front-end.
|
||||
</Card>
|
||||
<Card title="Operazioni" icon="rocket" href="/l/it/developers/extend/apps/operations/overview">
|
||||
CLI, test, remoti, CI e pubblicazione della tua app.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Scaffolding
|
||||
description: "Genera i file delle entità in modo interattivo con yarn twenty dev:add: oggetti, campi, viste, funzioni di logica e altro ancora."
|
||||
icon: wand-magic-sparkles
|
||||
---
|
||||
|
||||
Invece di creare manualmente i file delle entità, puoi usare lo scaffolder interattivo:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty dev:add
|
||||
```
|
||||
|
||||
Ti chiede di scegliere un tipo di entità e ti guida attraverso i campi richiesti, quindi scrive un file pronto all’uso con un `universalIdentifier` stabile e la corretta chiamata a `defineEntity()`.
|
||||
|
||||
Puoi anche passare direttamente il tipo di entità per saltare il primo prompt:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty dev:add object
|
||||
yarn twenty dev:add logicFunction
|
||||
yarn twenty dev:add frontComponent
|
||||
```
|
||||
|
||||
## Tipi di entità disponibili
|
||||
|
||||
| Tipo di entità | Comando | File generato |
|
||||
| ---------------------------- | ---------------------------------------- | ------------------------------------------------------- |
|
||||
| Oggetto | `yarn twenty dev:add object` | `src/objects/\<name>.ts` |
|
||||
| Campo | `yarn twenty dev:add field` | `src/fields/\<name>.ts` |
|
||||
| Funzione logica | `yarn twenty dev:add logicFunction` | `src/logic-functions/\<name>.ts` |
|
||||
| Componente front-end | `yarn twenty dev:add frontComponent` | `src/front-components/\<name>.tsx` |
|
||||
| Ruolo | `yarn twenty dev:add role` | `src/roles/\<name>.ts` |
|
||||
| Abilità | `yarn twenty dev:add skill` | `src/skills/\<name>.ts` |
|
||||
| Agente | `yarn twenty dev:add agent` | `src/agents/\<name>.ts` |
|
||||
| Vista | `yarn twenty dev:add view` | `src/views/\<name>.ts` |
|
||||
| Voce del menu di navigazione | `yarn twenty dev:add navigationMenuItem` | `src/navigation-menu-items/\<name>.ts` |
|
||||
| Layout di pagina | `yarn twenty dev:add pageLayout` | `src/page-layouts/\<name>.ts` |
|
||||
|
||||
## Cosa genera lo scaffolder
|
||||
|
||||
Ogni tipo di entità ha il proprio template. Ad esempio, `yarn twenty dev:add object` richiede:
|
||||
|
||||
1. **Nome (singolare)** — ad es., `invoice`
|
||||
2. **Nome (plurale)** — ad es., `invoices`
|
||||
3. **Etichetta (singolare)** — compilata automaticamente dal nome (ad es., `Invoice`)
|
||||
4. **Etichetta (plurale)** — compilata automaticamente (ad es., `Invoices`)
|
||||
5. **Creare una vista e una voce di navigazione?** — se rispondi sì, lo scaffolder genera anche una vista corrispondente e un link nella barra laterale per il nuovo oggetto.
|
||||
|
||||
Gli altri tipi di entità hanno prompt più semplici — la maggior parte chiede solo un nome.
|
||||
|
||||
Il tipo di entità `field` è più dettagliato: chiede il nome del campo, l'etichetta, il tipo (da un elenco di tutti i tipi di campo disponibili come `TEXT`, `NUMBER`, `SELECT`, `RELATION`, ecc.) e l'`universalIdentifier` dell'oggetto di destinazione.
|
||||
|
||||
## Percorso di output personalizzato
|
||||
|
||||
Usa il flag `--path` per posizionare il file generato in una posizione personalizzata:
|
||||
|
||||
```bash filename="Terminal"
|
||||
yarn twenty dev:add logicFunction --path src/custom-folder
|
||||
```
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Risoluzione dei problemi
|
||||
description: Problemi comuni al primo avvio — Docker, versione di Node, Yarn, dipendenze.
|
||||
icon: wrench
|
||||
---
|
||||
|
||||
* **Errori di Docker** — Assicurati che Docker Desktop (o il demone) sia in esecuzione prima di `yarn twenty docker:start`. Il messaggio di errore mostrerà il comando di avvio corretto per il tuo sistema operativo.
|
||||
* **Versione di Node errata** — È necessaria la versione 24 o superiore. Verifica con `node -v`.
|
||||
* **Manca Yarn 4** — Esegui `corepack enable`.
|
||||
* **Dipendenze danneggiate** — `rm -rf node_modules && yarn install`.
|
||||
* **Errori di `twenty-sdk` dopo l'aggiornamento alla v2.8.0** — è stato spostato da `dependencies` a `devDependencies` nella v2.8.0. Vedi [Struttura del progetto → Dipendenze](/l/it/developers/extend/apps/getting-started/project-structure#dependencies).
|
||||
* **`twenty build` mostra un avviso su `twenty-client-sdk` sotto `dependencies`** — viene fornito in fase di esecuzione da Twenty, quindi dovrebbe essere spostato in `devDependencies` insieme a `twenty-sdk`. Vedi [Struttura del progetto → Dipendenze](/l/it/developers/extend/apps/getting-started/project-structure#dependencies).
|
||||
|
||||
Bloccato? Chiedi aiuto su [Discord di Twenty](https://discord.com/channels/1130383047699738754/1130386664812982322).
|
||||
Reference in New Issue
Block a user