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
8.8 KiB
Plaintext
124 lines
8.8 KiB
Plaintext
---
|
||
title: Konfigurace aplikace
|
||
description: Deklarujte identitu své aplikace, výchozí roli, proměnné a metadata tržiště pomocí defineApplication.
|
||
icon: rocket
|
||
---
|
||
|
||
Každá aplikace musí mít právě jedno volání `defineApplication`. Deklaruje:
|
||
|
||
* **Identita** — univerzální identifikátor, zobrazovaný název, popis.
|
||
* **Oprávnění** — pod jakou rolí běží její logické funkce a frontendové komponenty.
|
||
* **Proměnné** *(volitelné)* — páry klíč–hodnota zpřístupněné vašemu kódu jako proměnné prostředí.
|
||
* **Předinstalační / postinstalační / odinstalační hooky** *(volitelné)* — viz [Logické funkce](/l/cs/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,
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
Poznámky:
|
||
|
||
* Pole `universalIdentifier` jsou deterministické identifikátory, které vlastníte. Vygenerujte je jednou a zachovejte je stabilní napříč synchronizacemi.
|
||
* `applicationVariables` se stanou proměnnými prostředí pro vaše funkce a frontendové komponenty. V logických funkcích (na straně serveru) jsou dostupné jako `process.env.VARIABLE_NAME`. Ve frontendových komponentách použijte `getApplicationVariable('VARIABLE_NAME')` z `twenty-sdk/front-component`. Proměnné označené jako `isSecret: true` jsou předávány pouze do logických funkcí. Frontendové komponenty přijímají pouze proměnné, které nejsou tajné.
|
||
* Výchozí role je automaticky detekována ze souboru role označeného pomocí [`defineApplicationRole()`](/l/cs/developers/extend/apps/config/roles) — není potřeba na ni odkazovat z `defineApplication()`.
|
||
* Předinstalační, postinstalační a odinstalační funkce jsou při sestavení manifestu detekovány automaticky — není třeba na ně odkazovat v `defineApplication()`.
|
||
* Předávání `defaultRoleUniversalIdentifier` explicitně je stále podporováno kvůli zpětné kompatibilitě, ale je zastaralé ve prospěch `defineApplicationRole()`.
|
||
* `serverVariables` představují konfiguraci a tajné údaje vázané na instanci (např. klíče API). Na rozdíl od `applicationVariables` neuvádějí v manifestu žádnou hodnotu — operátor pracovního prostoru je vyplní v nastavení aplikace a do logických funkcí jsou injektovány až poté, co jsou nastaveny.
|
||
* Chcete-li vykreslit vlastní konfigurační uživatelské rozhraní na kartě **Settings** aplikace (namísto výchozí sekce pro konfiguraci proměnných), deklarujte frontovou komponentu pomocí [`defineSettingsFrontComponent()`](/l/cs/developers/extend/apps/layout/front-components#custom-settings-component) v jejím vlastním souboru. Na jednu aplikaci je povolena pouze jedna instance. Sekce spravované systémem (automatická aktualizace, App URL, připojení) zůstávají vždy viditelné.
|
||
|
||
## Typy proměnných
|
||
|
||
Jak `applicationVariables`, tak `serverVariables` přijímají volitelný `type` (a pro `SELECT` / `MULTI_SELECT` i seznam `options`). Podporované typy: `TEXT` (výchozí), `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',
|
||
},
|
||
},
|
||
});
|
||
```
|
||
|
||
`type` ovlivňuje pouze **prezentaci a validaci** — v uživatelském rozhraní nastavení pracovního prostoru vybere odpovídající vstup (přepínač, číselné pole, rozbalovací seznam, výběr data, editor JSON, …) a umožní sestavení ověřit vaši konfiguraci (například `SELECT` / `MULTI_SELECT` musí deklarovat neprázdné `options`). Nijak **nemění** způsob, jakým se hodnota dostane do vašeho kódu.
|
||
|
||
Hodnoty jsou **vždy předávány jako řetězce** — je to dáno povahou proměnných prostředí (`process.env.*` obsahuje pouze řetězce). Když se spustí vaše logická funkce, executor serializuje každou hodnotu podle jejího deklarovaného `type` při sestavování `process.env`, takže formát řetězce je konzistentní bez ohledu na to, jak byla hodnota nastavena (výchozí hodnota v manifestu, v uživatelském rozhraní nastavení nebo v předchozí verzi):
|
||
|
||
| Typ | řetězec `process.env` |
|
||
| ------------------------------------- | --------------------------------------- |
|
||
| `TEXT`, `SELECT`, `DATE`, `DATE_TIME` | surová hodnota (`"eu"`, `"2026-01-01"`) |
|
||
| `BOOLEAN` | `"true"` / `"false"` |
|
||
| `NUMBER`, `NUMERIC` | desetinný řetězec (`"10"`, `"2.5"`) |
|
||
| `MULTI_SELECT`, `ARRAY` | JSON pole (`'["email","postcard"]'`) |
|
||
| `RAW_JSON`, `RICH_TEXT` | JSON objekt (`'{"retries":3}'`) |
|
||
|
||
Parsujte řetězec zpět do typu, který očekáváte:
|
||
|
||
```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 }
|
||
```
|
||
|
||
Totéž platí pro frontendové komponenty, které čtou hodnoty pomocí `getApplicationVariable('VARIABLE_NAME')` — vrácená hodnota je řetězec; podle potřeby ji parsujte.
|
||
|
||
## Výchozí role funkce
|
||
|
||
Role deklarovaná pomocí [`defineApplicationRole()`](/l/cs/developers/extend/apps/config/roles) určuje, k čemu mají přístup logické funkce a front-endové komponenty aplikace:
|
||
|
||
* Běhový token vložený jako `TWENTY_APP_ACCESS_TOKEN` je odvozen z této role.
|
||
* Typovaný klient API je omezen na oprávnění udělená této roli.
|
||
* Dodržujte princip nejmenších oprávnění: deklarujte pouze ta oprávnění, která vaše funkce potřebují.
|
||
|
||
Když vygenerujete novou aplikaci, CLI vytvoří úvodní soubor role v `src/roles/default-role.ts`. Úplnou referenci najdete v části [Role a oprávnění](/l/cs/developers/extend/apps/config/roles).
|
||
|
||
## Metadata tržiště
|
||
|
||
Pokud plánujete [zveřejnit svou aplikaci](/l/cs/developers/extend/apps/operations/publishing), tato volitelná pole určují, jak se vaše aplikace zobrazuje v tržišti:
|
||
|
||
| Pole | Popis |
|
||
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
|
||
| `author` | Jméno autora nebo název společnosti |
|
||
| `category` | Kategorie aplikace pro filtrování v tržišti |
|
||
| `logo` | Cesta k logu vaší aplikace uloženému ve složce `public/` (např. `public/logo.png`) |
|
||
| `galleryImages` | Pole cest ke snímkům galerie uloženým ve složce `public/` (např. `public/screenshot-1.png`) |
|
||
| `aboutDescription` | Delší popis v Markdownu pro kartu "O aplikaci". Pokud je vynecháno, tržiště použije `README.md` balíčku z npm |
|
||
| `websiteUrl` | Odkaz na váš web |
|
||
| `termsUrl` | Odkaz na podmínky služby |
|
||
| `emailSupport` | E-mailová adresa podpory |
|
||
| `issueReportUrl` | Odkaz na nástroj pro sledování problémů |
|
||
|
||
<Note>
|
||
`logoUrl` a `screenshots` jsou zastaralé aliasy `logo` a `galleryImages`. Externí absolutní adresy URL (`http://` nebo `https://`) nejsou pro tato pole podporovány: při sestavení jsou vynechány s varováním. Místo toho přiložte obrázky do složky `public/` vaší aplikace.
|
||
</Note>
|