> ## Documentation Index > Fetch the complete documentation index at: https://docs.twenty.com/llms.txt > Use this file to discover all available pages before exploring further. # Configuração da aplicação > Declare a identidade do seu app, o papel padrão, as variáveis e os metadados de marketplace com `defineApplication`. Todo app deve ter exatamente uma chamada a `defineApplication`. Ela declara: * **Identidade** — identificador universal, nome de exibição, descrição. * **Permissões** — qual papel é usado pelas suas funções de lógica e pelos componentes de front-end. * **Variáveis** *(opcional)* — pares chave–valor expostos ao seu código como variáveis de ambiente. * **Hooks de pré-instalação/pós-instalação/desinstalação** *(opcional)* — consulte [Funções de lógica](/l/pt/developers/extend/apps/logic/logic-functions). ```ts src/application-config.ts theme={null} 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, }, }, }); ``` Notas: * Os campos `universalIdentifier` são IDs determinísticos que você controla. Gere-os uma vez e mantenha-os estáveis entre sincronizações. * `applicationVariables` tornam-se variáveis de ambiente para suas funções e componentes de front-end. Em funções lógicas (no lado do servidor), elas ficam disponíveis como `process.env.VARIABLE_NAME`. Em componentes de front-end, use `getApplicationVariable('VARIABLE_NAME')` de `twenty-sdk/front-component`. Variáveis marcadas com `isSecret: true` são injetadas apenas em funções lógicas. Componentes de front-end recebem apenas variáveis não secretas. * O papel padrão é detectado automaticamente a partir do arquivo de definição de papel marcado com [`defineApplicationRole()`](/l/pt/developers/extend/apps/config/roles) — você não precisa referenciá-lo em `defineApplication()`. * As funções de pré-instalação, pós-instalação e desinstalação são detectadas automaticamente durante a construção do manifesto — você não precisa referenciá-las em `defineApplication()`. * Passar `defaultRoleUniversalIdentifier` explicitamente ainda é compatível para retrocompatibilidade, mas foi preterido em favor de `defineApplicationRole()`. * `serverVariables` são configurações e segredos com escopo de instância (por exemplo, chaves de API). Ao contrário de `applicationVariables`, eles não declaram nenhum valor no manifesto — o operador do workspace os preenche nas configurações do app, e eles são injetados nas funções de lógica somente depois de definidos. * Para renderizar uma interface de configuração personalizada na guia **Configurações** do app (no lugar da seção padrão de configuração de variáveis), declare um componente de front-end com [`defineSettingsFrontComponent()`](/l/pt/developers/extend/apps/layout/front-components#custom-settings-component) em seu próprio arquivo. Só é permitido um por app. Seções gerenciadas pelo sistema (atualização automática, URL do app, conexões) permanecem sempre visíveis. ## Tipos de variáveis Tanto `applicationVariables` quanto `serverVariables` aceitam um `type` opcional (e, para `SELECT` / `MULTI_SELECT`, uma lista de `options`). Tipos compatíveis: `TEXT` (padrão), `BOOLEAN`, `NUMBER`, `NUMERIC`, `DATE`, `DATE_TIME`, `SELECT`, `MULTI_SELECT`, `ARRAY`, `RAW_JSON`, `RICH_TEXT`. ```ts src/application-config.ts theme={null} 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', }, }, }); ``` O `type` afeta apenas a **apresentação e validação** — ele seleciona a entrada correspondente na interface de configurações do workspace (um toggle, campo numérico, dropdown, seletor de data, editor JSON, …) e permite que o build valide a sua configuração (por exemplo, `SELECT` / `MULTI_SELECT` devem declarar `options` não vazias). Ele **não** altera a forma como o valor chega ao seu código. Os valores são **sempre injetados como strings** — isso é inerente às variáveis de ambiente (`process.env.*` aceita apenas string). Quando a sua função de lógica é executada, o executor serializa cada valor de acordo com o `type` declarado ao construir o `process.env`, para que o formato da string seja consistente, não importa como o valor foi definido (padrão do manifesto, interface de configurações ou uma versão anterior): | Tipo | string de `process.env` | | ------------------------------------- | -------------------------------------- | | `TEXT`, `SELECT`, `DATE`, `DATE_TIME` | o valor bruto (`"eu"`, `"2026-01-01"`) | | `BOOLEAN` | `"true"` / `"false"` | | `NUMBER`, `NUMERIC` | string decimal (`"10"`, `"2.5"`) | | `MULTI_SELECT`, `ARRAY` | array JSON (`'["email","postcard"]'`) | | `RAW_JSON`, `RICH_TEXT` | objeto JSON (`'{"retries":3}'`) | Converta a string de volta para o tipo que você espera: ```ts theme={null} 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 } ``` O mesmo se aplica a componentes de front-end que leem valores via `getApplicationVariable('VARIABLE_NAME')` — o valor retornado é uma string; converta conforme necessário. ## Papel de função padrão O papel declarado com [`defineApplicationRole()`](/l/pt/developers/extend/apps/config/roles) controla o que as funções de lógica e os componentes de front-end do aplicativo podem acessar: * O token em tempo de execução injetado como `TWENTY_APP_ACCESS_TOKEN` é derivado desse papel. * O cliente de API tipado é restrito às permissões concedidas a esse papel. * Siga o princípio do menor privilégio: declare apenas as permissões de que suas funções precisam. Ao criar um novo app com o scaffold, a CLI cria um arquivo de papel inicial em `src/roles/default-role.ts`. Consulte [Papéis e permissões](/l/pt/developers/extend/apps/config/roles) para a referência completa. ## Metadados do Marketplace Se você planeja [publicar seu app](/l/pt/developers/extend/apps/operations/publishing), estes campos opcionais controlam como seu app aparece no marketplace: | Campo | Descrição | | ------------------ | ----------------------------------------------------------------------------------------------------------------- | | `author` | Nome do autor ou da empresa | | `category` | Categoria do app para filtragem no marketplace | | `logo` | Caminho para o logotipo do seu aplicativo empacotado em `public/` (p. ex., `public/logo.png`) | | `galleryImages` | Array de caminhos de imagem da galeria empacotado em `public/` (por exemplo, `public/screenshot-1.png`) | | `aboutDescription` | Descrição em markdown mais longa para a aba "Sobre". Se omitido, o marketplace usa o `README.md` do pacote no npm | | `websiteUrl` | Link para seu site | | `termsUrl` | Link para os Termos de Serviço | | `emailSupport` | Endereço de e-mail de suporte | | `issueReportUrl` | Link para o rastreador de problemas | `logoUrl` e `screenshots` são aliases depreciadas de `logo` e `galleryImages`. URLs absolutas externas (`http://` ou `https://`) não são suportados para estes campos: eles são descartados com um aviso no momento da compilação. Agrupe as imagens na pasta `public/` do seu aplicativo.