Configuração da aplicação

• 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.

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,
    },
  },
});

• 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() — 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() 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

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',
    },
  },
});

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 }

​

Papel de função padrão

• 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.

​

Metadados do Marketplace