Saltar para o conteúdo principal
As aplicações Twenty são pacotes TypeScript que estendem seu espaço de trabalho com objetos personalizados, lógica, componentes de UI e recursos de IA. Elas são executadas na plataforma Twenty com sandboxing completo e controles de permissão.

​
Como as aplicações funcionam

Uma aplicação é uma coleção de entidades declaradas usando funções defineEntity() do pacote twenty-sdk. O SDK detecta essas declarações via análise de AST no momento da compilação e produz um manifesto — uma descrição completa do que seu aplicativo adiciona a um espaço de trabalho. Essas funções validam sua configuração em tempo de compilação e oferecem autocompletar na IDE e segurança de tipos. 
your-app/
├── src/
│   ├── application-config.ts    ← defineApplication (required, one per app)
│   ├── roles/                   ← defineRole
│   ├── objects/                 ← defineObject
│   ├── fields/                  ← defineField
│   ├── logic-functions/         ← defineLogicFunction
│   ├── front-components/        ← defineFrontComponent
│   ├── skills/                  ← defineSkill
│   ├── agents/                  ← defineAgent
│   ├── views/                   ← defineView
│   ├── navigation-menu-items/   ← defineNavigationMenuItem
│   └── page-layouts/            ← definePageLayout
├── public/                      ← Static assets (images, icons)
└── package.json
A organização de arquivos fica a seu critério. A detecção de entidades é baseada em AST — o SDK encontra chamadas a export default defineEntity(...) independentemente de onde o arquivo esteja. A estrutura de pastas acima é uma convenção, não um requisito.

​
Tipos de entidade

EntidadeFinalidadeDocumentação
AplicaçãoIdentidade da aplicação, função padrão, variáveisConfiguração da aplicação
PapelConjuntos de permissões para objetos e camposPapéis e permissões
ObjetoTipos de registro personalizados com camposObjetos
CampoAdicionar campos a objetos de outros appsExtensão de objetos
RelaçãoLinks bidirecionais entre objetosRelações
Função lógicaTypeScript no lado do servidor com gatilhosFunções lógicas
HabilidadeInstruções reutilizáveis para agentes de IAHabilidades e Agentes
AgenteAssistentes de IA com prompts personalizadosHabilidades e Agentes
Provedor de conexãoCredenciais OAuth para APIs de terceirosConexões
VistaVistas de lista de registros pré-configuradasVistas
Item do menu de navegaçãoEntradas personalizadas na barra lateralItens do menu de navegação
Layout da PáginaAbas e widgets na página de detalhes de um registroLayouts de página
Componente de front-endUI React em sandbox dentro do TwentyComponentes de front-end
Item do menu de comandosAções rápidas e entradas Cmd+KItens do menu de comandos

​
Sandboxing

  • Funções lógicas são executadas em processos Node.js isolados no servidor. Elas acessam dados apenas por meio do cliente de API tipado, restrito às permissões do papel do aplicativo.
  • Componentes de front-end executam em Web Workers usando Remote DOM — isolados da página principal, mas renderizando elementos DOM nativos (não iframes). Eles se comunicam com o Twenty por meio de uma API de host com passagem de mensagens.
  • Permissões são aplicadas no nível da API. O token de tempo de execução (TWENTY_APP_ACCESS_TOKEN) é derivado do papel definido em defineApplication().

​
Ciclo de vida do aplicativo

┌─────────────────────────────────────────────────────────┐
│ Development                                             │
│   npx create-twenty-app → yarn twenty dev (live sync)   │
├─────────────────────────────────────────────────────────┤
│ Build & Deploy                                          │
│   yarn twenty dev:build → yarn twenty app:publish        │
├─────────────────────────────────────────────────────────┤
│ Install flow                                            │
│   upload → [pre-install] → metadata migration →         │
│   generate SDK → [post-install]                         │
├─────────────────────────────────────────────────────────┤
│ Publish                                                 │
│   npm publish → appears in Twenty marketplace           │
└─────────────────────────────────────────────────────────┘
  • yarn twenty dev — observa seus arquivos-fonte e sincroniza ao vivo as alterações com um servidor Twenty conectado. O cliente de API tipado é regenerado automaticamente quando o esquema muda.
  • yarn twenty dev:build — compila TypeScript, empacota funções de lógica e componentes de front-end com o esbuild e produz um manifesto.
  • Hooks de pré/pós-instalação — funções opcionais que são executadas durante a instalação. Veja Hooks de instalação para detalhes.

​
Próximos passos

Configuração

Identidade da aplicação, função padrão e hooks de instalação.

Dados

Objetos, campos e relações bidirecionais.

Lógica

Funções lógicas, habilidades, agentes e conexões OAuth.

Layout

Vistas, navegação, layouts de página, componentes de front-end.

Operações

CLI, testes, remotos, CI e publicação do seu aplicativo.