Conceitos

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

Entidade	Finalidade	Documentação
Aplicação	Identidade da aplicação, função padrão, variáveis	Configuração da aplicação
Papel	Conjuntos de permissões para objetos e campos	Papéis e permissões
Objeto	Tipos de registro personalizados com campos	Objetos
Campo	Adicionar campos a objetos de outros apps	Extensão de objetos
Relação	Links bidirecionais entre objetos	Relações
Função lógica	TypeScript no lado do servidor com gatilhos	Funções lógicas
Habilidade	Instruções reutilizáveis para agentes de IA	Habilidades e Agentes
Agente	Assistentes de IA com prompts personalizados	Habilidades e Agentes
Provedor de conexão	Credenciais OAuth para APIs de terceiros	Conexões
Vista	Vistas de lista de registros pré-configuradas	Vistas
Item do menu de navegação	Entradas personalizadas na barra lateral	Itens do menu de navegação
Layout da Página	Abas e widgets na página de detalhes de um registro	Layouts de página
Componente de front-end	UI React em sandbox dentro do Twenty	Componentes de front-end
Item do menu de comandos	Ações rápidas e entradas Cmd+K	Itens 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] → … → [uninstall]       │
├─────────────────────────────────────────────────────────┤
│ 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 e desinstalação — funções opcionais que são executadas durante a instalação ou logo antes da remoçã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 e desinstalaçã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.

Visão Geral

Aplicativos

API

Auto-Anfitrião

Contribuir

Como as aplicações funcionam

Tipos de entidade

Sandboxing

Ciclo de vida do aplicativo

Próximos passos

Configuração

Dados

Lógica

Layout

Operações

​Como as aplicações funcionam

​Tipos de entidade

​Sandboxing

​Ciclo de vida do aplicativo

​Próximos passos

Configuração

Dados

Lógica

Layout

Operações

Como as aplicações funcionam

Tipos de entidade

Sandboxing

Ciclo de vida do aplicativo

Próximos passos