github-actions[bot]
ad3291f4b4
Created by Github action <!-- This is an auto-generated description by cubic. --> <a href="https://cubic.dev/pr/twentyhq/twenty/pull/23338?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> Co-authored-by: github-actions <github-actions@twenty.com>
124 lines
9.2 KiB
Plaintext
124 lines
9.2 KiB
Plaintext
---
|
||
title: Configurazione dell'applicazione
|
||
description: Dichiara l'identità della tua app, il ruolo predefinito, le variabili e i metadati del marketplace con defineApplication.
|
||
icon: rocket
|
||
---
|
||
|
||
Ogni app deve avere esattamente una chiamata a `defineApplication`. Dichiara:
|
||
|
||
* **Identità** — identificatore universale, nome visualizzato, descrizione.
|
||
* **Autorizzazioni** — il ruolo sotto il quale vengono eseguite le sue funzioni logiche e i componenti front-end.
|
||
* **Variabili** *(opzionali)* — coppie chiave–valore esposte al tuo codice come variabili d'ambiente.
|
||
* **Hook di pre-installazione / post-installazione / disinstallazione** *(opzionali)* — vedi [Funzioni logiche](/l/it/developers/extend/apps/logic/logic-functions).
|
||
|
||
```ts src/application-config.ts
|
||
import { defineApplication } from 'twenty-sdk/define';
|
||
|
||
export default defineApplication({
|
||
universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
|
||
displayName: 'My Twenty App',
|
||
description: 'My first Twenty app',
|
||
applicationVariables: {
|
||
DEFAULT_RECIPIENT_NAME: {
|
||
universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
|
||
description: 'Default recipient name for postcards',
|
||
value: 'Jane Doe',
|
||
isSecret: false,
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
Note:
|
||
|
||
* I campi `universalIdentifier` sono ID deterministici che possiedi. Generali una volta e mantienili stabili tra una sincronizzazione e l'altra.
|
||
* `applicationVariables` diventano variabili d'ambiente per le tue funzioni e i componenti front-end. Nelle funzioni di logica (lato server), sono disponibili come `process.env.VARIABLE_NAME`. Nei componenti front-end, usa `getApplicationVariable('VARIABLE_NAME')` da `twenty-sdk/front-component`. Le variabili contrassegnate con `isSecret: true` vengono iniettate solo nelle funzioni di logica. I componenti front-end ricevono solo variabili non segrete.
|
||
* Il ruolo predefinito viene rilevato automaticamente dal file di ruolo contrassegnato con [`defineApplicationRole()`](/l/it/developers/extend/apps/config/roles): non è necessario farvi riferimento da `defineApplication()`.
|
||
* Le funzioni di pre-installazione, post-installazione e disinstallazione vengono rilevate automaticamente durante il build del manifest — non è necessario farne riferimento in `defineApplication()`.
|
||
* Il passaggio esplicito di `defaultRoleUniversalIdentifier` è ancora supportato per garantire la compatibilità con le versioni precedenti, ma è deprecato a favore di `defineApplicationRole()`.
|
||
* `serverVariables` sono configurazioni e segreti con ambito di istanza (ad esempio chiavi API). A differenza di `applicationVariables`, non dichiarano alcun valore nel manifest — l’operatore dello spazio di lavoro li compila dalle impostazioni dell’app e vengono iniettati nelle funzioni di logica solo una volta impostati.
|
||
* Per eseguire il rendering di un'interfaccia di configurazione personalizzata all'interno della scheda **Settings** dell'app (al posto della sezione predefinita di configurazione delle variabili), dichiara un front component con [`defineSettingsFrontComponent()`](/l/it/developers/extend/apps/layout/front-components#custom-settings-component) in un proprio file. Ne è consentito solo uno per app. Le sezioni gestite dal sistema (auto-upgrade, App URL, connessioni) rimangono sempre visibili.
|
||
|
||
## Tipi di variabili
|
||
|
||
Sia `applicationVariables` che `serverVariables` accettano un `type` opzionale (e, per `SELECT` / `MULTI_SELECT`, un elenco di `options`). Tipi supportati: `TEXT` (predefinito), `BOOLEAN`, `NUMBER`, `NUMERIC`, `DATE`, `DATE_TIME`, `SELECT`, `MULTI_SELECT`, `ARRAY`, `RAW_JSON`, `RICH_TEXT`.
|
||
|
||
```ts src/application-config.ts
|
||
import { defineApplication, FieldType } from 'twenty-sdk/define';
|
||
|
||
export default defineApplication({
|
||
// ...identity, role...
|
||
applicationVariables: {
|
||
MAX_POSTCARDS: {
|
||
universalIdentifier: '5f4497e4-9030-4085-85eb-2c48b8d53713',
|
||
description: 'Maximum postcards per batch',
|
||
type: FieldType.NUMBER,
|
||
value: 10,
|
||
},
|
||
DEFAULT_REGION: {
|
||
universalIdentifier: '76c5c321-b6b6-46eb-b4fc-f9f04bb04227',
|
||
description: 'Default shipping region',
|
||
type: FieldType.SELECT,
|
||
options: [
|
||
{ label: 'Europe', value: 'eu' },
|
||
{ label: 'United States', value: 'us' },
|
||
],
|
||
value: 'eu',
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
Il `type` influisce solo su **presentazione e convalida**: seleziona l’input corrispondente nell’interfaccia delle impostazioni dell’area di lavoro (un interruttore, campo numerico, menu a discesa, selettore di data, editor JSON, …) e consente alla build di convalidare la tua configurazione (ad esempio, `SELECT` / `MULTI_SELECT` devono dichiarare `options` non vuote). **Non** cambia il modo in cui il valore arriva al tuo codice.
|
||
|
||
I valori sono **sempre inseriti come stringhe**: ciò è intrinseco alle variabili di ambiente (`process.env.*` accetta solo stringhe). Quando la tua funzione di logica viene eseguita, l’executor serializza ogni valore in base al `type` dichiarato mentre costruisce `process.env`, quindi il formato della stringa è coerente indipendentemente da come è stato impostato il valore (valore predefinito del manifest, interfaccia delle impostazioni o una versione precedente):
|
||
|
||
| Tipo | stringa di `process.env` |
|
||
| ------------------------------------- | ----------------------------------------- |
|
||
| `TEXT`, `SELECT`, `DATE`, `DATE_TIME` | il valore grezzo (`"eu"`, `"2026-01-01"`) |
|
||
| `BOOLEAN` | `"true"` / `"false"` |
|
||
| `NUMBER`, `NUMERIC` | stringa decimale (`"10"`, `"2.5"`) |
|
||
| `MULTI_SELECT`, `ARRAY` | array JSON (`'["email","postcard"]'`) |
|
||
| `RAW_JSON`, `RICH_TEXT` | oggetto JSON (`'{"retries":3}'`) |
|
||
|
||
Analizza nuovamente la stringa nel tipo che ti aspetti:
|
||
|
||
```ts
|
||
const maxCards = Number(process.env.MAX_POSTCARDS); // "10" -> 10
|
||
const enabled = process.env.ENABLE_TRACKING === 'true'; // "true" -> true
|
||
const channels = JSON.parse(process.env.ENABLED_CHANNELS ?? '[]'); // '["email"]' -> ["email"]
|
||
const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3}' -> { retries: 3 }
|
||
```
|
||
|
||
Lo stesso vale per i componenti front-end che leggono i valori tramite `getApplicationVariable('VARIABLE_NAME')`: il valore restituito è una stringa; analizzalo secondo le necessità.
|
||
|
||
## Ruolo funzione predefinito
|
||
|
||
Il ruolo dichiarato con [`defineApplicationRole()`](/l/it/developers/extend/apps/config/roles) controlla a cosa possono accedere le funzioni di logica e i componenti di interfaccia dell'app:
|
||
|
||
* Il token di runtime iniettato come `TWENTY_APP_ACCESS_TOKEN` è derivato da questo ruolo.
|
||
* Il client API tipizzato è limitato alle autorizzazioni concesse a quel ruolo.
|
||
* Segui il principio del privilegio minimo: dichiara solo le autorizzazioni necessarie alle tue funzioni.
|
||
|
||
Quando esegui lo scaffolding di una nuova app, la CLI crea un file di ruolo iniziale in `src/roles/default-role.ts`. Per la documentazione completa, vedi [Ruoli e autorizzazioni](/l/it/developers/extend/apps/config/roles).
|
||
|
||
## Metadati del marketplace
|
||
|
||
Se prevedi di [pubblicare la tua app](/l/it/developers/extend/apps/operations/publishing), questi campi opzionali controllano come appare nel marketplace:
|
||
|
||
| Campo | Descrizione |
|
||
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `author` | Nome dell'autore o dell'azienda |
|
||
| `category` | Categoria dell'app per il filtraggio nel marketplace |
|
||
| `logo` | Percorso del logo dell'app in bundle in `public/` (ad esempio, `public/logo.png`) |
|
||
| `galleryImages` | Array dei percorsi delle immagini della galleria raggruppati in `public/` (ad esempio, `public/screenshot-1.png`) |
|
||
| `aboutDescription` | Descrizione markdown più lunga per la scheda "Informazioni". Se omesso, il marketplace utilizza il `README.md` del pacchetto da npm |
|
||
| `websiteUrl` | Link al tuo sito web |
|
||
| `termsUrl` | Link ai Termini di servizio |
|
||
| `emailSupport` | Indirizzo email di supporto |
|
||
| `issueReportUrl` | Link al sistema di tracciamento dei problemi |
|
||
|
||
<Note>
|
||
`logoUrl` e `screenshots` sono alias deprecati di `logo` e `galleryImages`. Gli URL assoluti esterni (`http://` o `https://`) non sono supportati per questi campi: vengono eliminati con un avviso al momento della generazione. Raccogli invece le immagini nella cartella `public/` della tua app.
|
||
</Note>
|