Co jsou aplikace?
Aplikace vám umožňují vytvářet a spravovat přizpůsobení Twenty jako kód. Místo konfigurace všeho přes uživatelské rozhraní definujete v kódu svůj datový model a logické funkce — což zrychluje vývoj, údržbu i nasazování do více pracovních prostorů. Co můžete dělat už dnes:- Definujte vlastní objekty a pole jako kód (spravovaný datový model)
- Vytvářejte logické funkce s vlastními spouštěči
- Nasazujte stejnou aplikaci do více pracovních prostorů
Předpoklady
- Node.js 24+ a Yarn 4
- Pracovní prostor Twenty a klíč API (vytvořte si jej na https://app.twenty.com/settings/api-webhooks)
Začínáme
Vytvořte novou aplikaci pomocí oficiálního scaffolderu, poté se ověřte a začněte vyvíjet:Struktura projektu (vytvořená scaffolderem)
Když spustítenpx create-twenty-app@latest my-twenty-app, scaffolder:
- Zkopíruje minimální základní aplikaci do
my-twenty-app/ - Přidá lokální závislost
twenty-sdka konfiguraci pro Yarn 4 - Vytvoří konfigurační soubory a skripty napojené na
twentyCLI - Vygeneruje výchozí konfiguraci aplikace a výchozí roli funkcí
- package.json: Declares the app name, version, engines (Node 24+, Yarn 4), and adds
twenty-sdkplus atwentyscript that delegates to the localtwentyCLI. Runyarn twenty helpto list all available commands. - .gitignore: Ignoruje běžné artefakty jako
node_modules,.yarn,generated/(typovaný klient),dist/,build/, složky s coverage, logy a soubory.env*. - yarn.lock, .yarnrc.yml, .yarn/: Zamykají a konfigurují nástrojový řetězec Yarn 4 používaný projektem.
- .nvmrc: Fixuje verzi Node.js požadovanou projektem.
- eslint.config.mjs a tsconfig.json: Poskytují lintování a konfiguraci TypeScriptu pro zdrojové soubory vaší aplikace v TypeScriptu.
- README.md: Krátké README v kořeni aplikace se základními pokyny.
- public/: Složka pro ukládání veřejných prostředků (obrázky, písma, statické soubory), které bude vaše aplikace poskytovat. Soubory umístěné zde se během synchronizace nahrají a jsou za běhu dostupné.
- src/: Hlavní místo, kde definujete svou aplikaci jako kód
Detekce entit
SDK detekuje entity analýzou vašich souborů TypeScript a hledá voláníexport default define<Entity>({...}). Každý typ entity má odpovídající pomocnou funkci exportovanou z twenty-sdk:
| Pomocná funkce | Typ entity |
|---|---|
defineObject() | Definice vlastních objektů |
defineLogicFunction() | Definice logických funkcí |
defineFrontComponent() | Definice frontendových komponent |
defineRole() | Definice rolí |
defineField() | Rozšíření polí u existujících objektů |
Pojmenování souborů je flexibilní. Detekce entit je založená na AST — SDK prochází vaše zdrojové soubory a hledá vzor
export default define<Entity>({...}). Soubory a složky můžete organizovat, jak chcete. Seskupování podle typu entity (např. logic-functions/, roles/) je pouze konvence pro organizaci kódu, nikoli požadavek.yarn twenty app:generatewill create agenerated/folder (typed Twenty client + workspace types).yarn twenty entity:addwill add entity definition files undersrc/for your custom objects, functions, front components, or roles.
Ověření
The first time you runyarn twenty auth:login, you’ll be prompted for:
- URL API (výchozí je http://localhost:3000 nebo váš aktuální profil pracovního prostoru)
- Klíč API
~/.twenty/config.json. Můžete spravovat více profilů a přepínat mezi nimi.
Správa pracovních prostorů
yarn twenty auth:switch, all subsequent commands will use that workspace by default. Můžete jej stále dočasně přepsat pomocí --workspace <name>.
Používejte zdroje SDK (typy a konfiguraci)
twenty-sdk poskytuje typované stavební bloky a pomocné funkce, které používáte ve své aplikaci. Níže jsou klíčové části, se kterými budete nejčastěji pracovat.Pomocné funkce
SDK poskytuje pomocné funkce pro definování entit vaší aplikace. Jak je popsáno v Detekce entit, musíte použítexport default define<Entity>({...}), aby byly vaše entity detekovány:
| Funkce | Účel |
|---|---|
defineApplication() | Nakonfigurujte metadata aplikace (povinné, jedno na aplikaci) |
defineObject() | Definice vlastních objektů s poli |
defineLogicFunction() | Definice logických funkcí s obslužnými funkcemi |
defineFrontComponent() | Definujte frontendové komponenty pro vlastní uživatelské rozhraní |
defineRole() | Konfigurace oprávnění rolí a přístupu k objektům |
defineField() | Rozšiřte existující objekty o další pole |
Definování objektů
Vlastní objekty popisují jak schéma, tak chování záznamů ve vašem pracovním prostoru. K definování objektů s vestavěnou validací použijtedefineObject():
- Použijte
defineObject()pro vestavěnou validaci a lepší podporu v IDE. - Hodnota
universalIdentifiermusí být jedinečná a stabilní napříč nasazeními. - Každé pole vyžaduje
name,type,labela svůj vlastní stabilníuniversalIdentifier. - Pole
fieldsje volitelné — objekty můžete definovat i bez vlastních polí. - You can scaffold new objects using
yarn twenty entity:add, which guides you through naming, fields, and relationships.
Základní pole jsou vytvořena automaticky. Když definujete vlastní objekt, Twenty automaticky přidá standardní pole jako
name, createdAt, updatedAt, createdBy, position a deletedAt. Nemusíte je definovat v poli fields — přidejte pouze svá vlastní pole.Konfigurace aplikace (application-config.ts)
Každá aplikace má jeden souborapplication-config.ts, který popisuje:
- Identitu aplikace: identifikátory, zobrazovaný název a popis.
- Jak běží její funkce: kterou roli používají pro oprávnění.
- (Volitelné) proměnné: dvojice klíč–hodnota zpřístupněné vašim funkcím jako proměnné prostředí.
defineApplication() to define your application configuration:
- Pole
universalIdentifierjsou deterministická ID, která vlastníte; vygenerujte je jednou a udržujte je stabilní napříč synchronizacemi. applicationVariablesse stanou proměnnými prostředí pro vaše funkce (napříkladDEFAULT_RECIPIENT_NAMEje dostupné jakoprocess.env.DEFAULT_RECIPIENT_NAME).defaultRoleUniversalIdentifierse musí shodovat se souborem role (viz níže).
Role a oprávnění
Aplikace mohou definovat role, které zapouzdřují oprávnění k objektům a akcím ve vašem pracovním prostoru. PoledefaultRoleUniversalIdentifier v application-config.ts určuje výchozí roli používanou logickými funkcemi vaší aplikace.
- Běhový klíč API vložený jako
TWENTY_API_KEYje odvozen z této výchozí role funkcí. - Typovaný klient bude omezen oprávněními udělenými této roli.
- Dodržujte princip nejmenších oprávnění: vytvořte vyhrazenou roli pouze s oprávněními, která vaše funkce potřebují, a poté odkazujte na její univerzální identifikátor.
Výchozí role funkce (*.role.ts)
Když vygenerujete novou aplikaci, CLI také vytvoří výchozí soubor role. K definování rolí s vestavěnou validací použijtedefineRole():
universalIdentifier této role se poté odkazuje v application-config.ts jako na defaultRoleUniversalIdentifier. Jinými slovy:
- *.role.ts definuje, co může výchozí role funkce dělat.
- application-config.ts ukazuje na tuto roli, aby vaše funkce zdědily její oprávnění.
- Začněte rolí vytvořenou scaffolderem a postupně ji omezujte podle principu nejmenších oprávnění.
- Nahraďte
objectPermissionsafieldPermissionsobjekty/poli, která vaše funkce potřebují. permissionFlagsřídí přístup k schopnostem na úrovni platformy. Držte je na minimu; přidávejte pouze to, co potřebujete.- Podívejte se na funkční příklad v aplikaci Hello World:
packages/twenty-apps/hello-world/src/roles/function-role.ts.
Konfigurace logických funkcí a vstupní bod
Každý soubor funkce používádefineLogicFunction() k exportu konfigurace s obslužnou funkcí (handlerem) a volitelnými spouštěči.
- route: Zpřístupní vaši funkci na HTTP cestě a metodě pod koncovým bodem
/s/:
např.path: '/post-card/create',-> volání na<APP_URL>/s/post-card/create
- cron: Spouští vaši funkci podle plánu pomocí výrazu CRON.
- databaseEvent: Spouští se při událostech životního cyklu objektů v pracovním prostoru. Když je operace události
updated, lze konkrétní sledovaná pole určit v poliupdatedFields. Pokud zůstane nedefinované nebo prázdné, spustí funkci jakákoli aktualizace.
např. person.updated
Poznámky:
- Pole
triggersje volitelné. Funkce bez spouštěčů lze použít jako pomocné funkce volané jinými funkcemi. - V jedné funkci můžete kombinovat více typů spouštěčů.
Payload spouštěče trasy
Když spouštěč trasy vyvolá vaši logickou funkci, ta obdrží objektRoutePayload, který odpovídá formátu AWS HTTP API v2. Importujte typ z twenty-sdk:
RoutePayload má následující strukturu:
| Vlastnost | Typ | Popis |
|---|---|---|
headers | Record<string, string | undefined> | Záhlaví HTTP (pouze ta uvedená v forwardedRequestHeaders) |
queryStringParameters | Record<string, string | undefined> | Parametry query stringu (více hodnot spojených čárkami) |
pathParameters | Record<string, string | undefined> | Parametry cesty extrahované ze vzoru trasy (např. /users/:id → { id: '123' }) |
text zprávy | object | null | Parsované tělo požadavku (JSON) |
isBase64Encoded | booleovská hodnota | Zda je tělo kódováno base64 |
requestContext.http.method | string | Metoda HTTP (GET, POST, PUT, PATCH, DELETE) |
requestContext.http.path | string | Nezpracovaná cesta požadavku |
Přeposílání záhlaví HTTP
Ve výchozím nastavení se záhlaví HTTP z příchozích požadavků z bezpečnostních důvodů do vaší logické funkce ne předávají. Chcete-li zpřístupnit konkrétní záhlaví, výslovně je uveďte v poliforwardedRequestHeaders:
Názvy záhlaví jsou normalizovány na malá písmena. Přistupujte k nim pomocí klíčů s malými písmeny (například
event.headers['content-type']).- Scaffolded: Run
yarn twenty entity:addand choose the option to add a new logic function. Tím se vygeneruje startovací soubor s obslužnou funkcí a konfigurací. - Ruční: Vytvořte nový soubor
*.logic-function.tsa použijtedefineLogicFunction()podle stejného vzoru.
Frontendové komponenty
Frontendové komponenty vám umožňují vytvářet vlastní React komponenty, které se vykreslují v rozhraní Twenty. K definování komponent s vestavěnou validací použijtedefineFrontComponent():
- Frontendové komponenty jsou React komponenty, které se vykreslují v izolovaných kontextech v rámci Twenty.
- Pro automatickou detekci použijte příponu souboru
*.front-component.tsx. - Pole
componentodkazuje na vaši React komponentu. - Components are built and synced automatically during
yarn twenty app:dev.
- Scaffolded: Run
yarn twenty entity:addand choose the option to add a new front component. - Ruční: Vytvořte nový soubor
*.front-component.tsxa použijtedefineFrontComponent().
Generovaný typovaný klient
Runyarn twenty app:generate to create a local typed client in generated/ based on your workspace schema. Použijte jej ve svých funkcích:
yarn twenty app:generate. Spusťte znovu po změně vašich objektů nebo při připojování k novému pracovnímu prostoru.
Běhové přihlašovací údaje v logických funkcích
Když vaše funkce běží na Twenty, platforma před spuštěním kódu vloží přihlašovací údaje jako proměnné prostředí:TWENTY_API_URL: Základní URL Twenty API, na které vaše aplikace cílí.TWENTY_API_KEY: Krátkodobý klíč s rozsahem omezeným na výchozí roli funkce vaší aplikace.
- Není nutné předávat URL ani klíč API vygenerovanému klientovi. Za běhu čte
TWENTY_API_URLaTWENTY_API_KEYz process.env. - Oprávnění klíče API jsou určena rolí odkazovanou ve vašem
application-config.tsprostřednictvímdefaultRoleUniversalIdentifier. Toto je výchozí role používaná logickými funkcemi vaší aplikace. - Aplikace mohou definovat role podle principu nejmenších oprávnění. Udělte pouze oprávnění, která vaše funkce potřebují, a poté nastavte
defaultRoleUniversalIdentifierna univerzální identifikátor této role.
Příklad Hello World
Prozkoumejte minimalistický end-to-end příklad, který demonstruje objekty, logické funkce, frontendové komponenty a více spouštěčů zde:Ruční nastavení (bez scaffolderu)
Ačkoli pro nejlepší začátky doporučujeme použítcreate-twenty-app, projekt můžete nastavit i ručně. Neinstalujte CLI globálně. Instead, add twenty-sdk as a local dependency and wire a single script in your package.json:
twenty script:
yarn twenty <command>, e.g. yarn twenty app:dev, yarn twenty app:generate, yarn twenty help, etc.
Řešení potíží
- Authentication errors: run
yarn twenty auth:loginand ensure your API key has the required permissions. - Nelze se připojit k serveru: ověřte URL API a že je server Twenty dosažitelný.
- Types or client missing/outdated: run
yarn twenty app:generate. - Dev mode not syncing: ensure
yarn twenty app:devis running and that changes are not ignored by your environment.