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. 
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, permissões, variáveisModelo de Dados
PapelConjuntos de permissões para objetos e camposModelo de Dados
ObjetoTabelas de dados personalizadas com camposModelo de Dados
CampoEstender objetos existentes, definir relaçõesModelo de Dados
Função lógicaTypeScript no lado do servidor com gatilhosFunções lógicas
Componente de front-endUI React em sandbox na página do TwentyComponentes de front-end
HabilidadeInstruções reutilizáveis para agentes de IAHabilidades e Agentes
AgenteAssistentes de IA com prompts personalizadosHabilidades e Agentes
VistaVistas de lista de registros pré-configuradasLayout
Item do menu de navegaçãoEntradas personalizadas na barra lateralLayout
Layout da PáginaAbas e widgets personalizados nas páginas de registroLayout

​
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 build → yarn twenty deploy                │
├─────────────────────────────────────────────────────────┤
│ 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 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 de lógica opcionais que são executadas durante a instalação. Veja Funções de Lógica para detalhes.

​
Próximos passos

Modelo de dados

Defina objetos, campos, papéis e relações.

Funções lógicas

Funções no lado do servidor com gatilhos HTTP, cron e de eventos.

Componentes de front-end

Componentes React em sandbox dentro da UI do Twenty.

Layout

Vistas, itens de navegação e layouts de página de registro.

Habilidades e agentes

Habilidades e agentes de IA com prompts personalizados.

CLI e Testes

Comandos de CLI, testes, assets, remotes e CI.

Publicação

Implante em um servidor ou publique no marketplace.