upstream-twenty/packages/twenty-docs/l/pt/developers/extend/apps/config/application.mdx

---
title: Configuração da aplicação
description: Declare a identidade do seu app, o papel padrão, as variáveis e os metadados de marketplace com `defineApplication`.
icon: rocket
---

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
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.
* Ambos os tipos de variável aceitam `isDeprecated: true`. Use isso para aposentar uma variável em vez de excluí-la: manter a chave declarada preserva o valor armazenado (excluí-la destrói o valor inserido pelo operador), e a variável ainda é injetada, para que seu código possa fazer fallback para ela — `process.env.NEW_API_KEY ?? process.env.API_KEY`. Uma variável obsoleta desaparece das configurações do aplicativo assim que não tiver valor e nunca é contabilizada na verificação de configuração do aplicativo, portanto `isDeprecated` prevalece sobre `isRequired`.
* 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
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
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:

* Os tokens de tempo de execução injetados nas suas funções de lógica são derivados desse papel. Uma chamada que atua como uma pessoa é ainda mais limitada pelo que essa pessoa pode fazer, portanto nunca pode exceder nenhum dos dois. Consulte [Qual acesso uma chamada usa](/l/pt/developers/extend/apps/logic/logic-functions#whose-access-a-call-uses).
* 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                                                                               |

<Note>
`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.
</Note>