Os aplicativos estão atualmente em testes alfa. O recurso é funcional, mas ainda está evoluindo.
O que são aplicativos?
Os aplicativos permitem que você estenda o Twenty com objetos e campos personalizados, funções lógicas, componentes de front-end, habilidades de IA e mais — tudo gerenciado como código. Em vez de configurar tudo pela UI, você define seu modelo de dados e a lógica em TypeScript e implanta em um ou mais workspaces.
Pré-requisitos
Antes de começar, verifique se o seguinte está instalado na sua máquina:
- Node.js 24+ — Baixe aqui
- Yarn 4 — Vem com o Node.js via Corepack. Ative-o executando
corepack enable
- Docker — Baixe aqui. Necessário para executar uma instância local do Twenty. Não é necessário se você já tiver um servidor Twenty em execução.
Crie seu primeiro aplicativo
Gere o scaffold do seu aplicativo
Abra um terminal e execute:
npx create-twenty-app@latest my-twenty-app
my-twenty-app com tudo de que você precisa.
O gerador de scaffold perguntará:
Você gostaria de configurar uma instância local do Twenty?
- Digite
yes (recomendado) — Isso baixa a imagem Docker twenty-app-dev e inicia um servidor Twenty local na porta 2020. Certifique-se de que o Docker esteja em execução antes de continuar.
- Digite
no — Escolha esta opção se você já tiver um servidor Twenty em execução localmente.
Faça login no seu espaço de trabalho
Em seguida, uma janela do navegador será aberta com a página de login do Twenty. Faça login com a conta de demonstração pré-configurada:
- E-mail:
tim@apple.dev
- Senha:
tim@apple.dev
Autorize o aplicativo
Após fazer login, você verá uma tela de autorização. Isso permite que seu aplicativo interaja com seu espaço de trabalho.
Clique em Authorize para continuar.
Depois de autorizado, seu terminal confirmará que tudo está configurado.
Comece a desenvolver
Entre na nova pasta do seu aplicativo e inicie o servidor de desenvolvimento:
cd my-twenty-app
yarn twenty dev
--verbose:
yarn twenty dev --verbose
O modo de desenvolvimento só está disponível em instâncias do Twenty em modo de desenvolvimento (NODE_ENV=development). Instâncias de produção rejeitam solicitações de sincronização de desenvolvimento. Use yarn twenty deploy para fazer o deploy em servidores de produção — veja Publicando aplicativos para detalhes. Veja seu aplicativo no Twenty
Abra http://localhost:2020/settings/applications#developer no seu navegador. Navegue até Settings > Apps e selecione a aba Developer. Você deverá ver seu aplicativo listado em Your Apps:
Clique em My twenty app para abrir o seu registro do aplicativo. Um registro é um registro em nível de servidor que descreve seu aplicativo — seu nome, identificador exclusivo, credenciais OAuth e origem (local, npm ou tarball). Ele reside no servidor, não dentro de nenhum espaço de trabalho específico. Quando você instala um aplicativo em um espaço de trabalho, o Twenty cria uma aplicação com escopo do espaço de trabalho que aponta para esse registro. Um registro pode ser instalado em vários espaços de trabalho no mesmo servidor.
Clique em View installed app para ver o aplicativo instalado. A aba About mostra a versão atual e as opções de gerenciamento:
Altere para a aba Content para ver tudo o que seu aplicativo oferece — objetos, campos, funções de lógica e agentes:
Tudo pronto! Edite qualquer arquivo em src/ e as alterações serão detectadas automaticamente.
O que você pode criar
Os aplicativos são compostos por entidades — cada uma definida como um arquivo TypeScript com um único export default:
| Entidade | O que faz |
|---|
| Objetos e campos | Defina modelos de dados personalizados (como cartão postal, fatura) com campos tipados |
| Funções lógicas | Funções TypeScript do lado do servidor acionadas por rotas HTTP, agendamentos do cron ou eventos de banco de dados |
| Componentes de front-end | Componentes React que são renderizados na UI do Twenty (painel lateral, widgets, menu de comandos) |
| Habilidades e agentes | Recursos de IA — instruções reutilizáveis e assistentes autônomos |
| Exibições e navegação | Exibições de lista pré-configuradas e itens de menu da barra lateral para seus objetos |
| Layouts de página | Páginas de detalhes de registros personalizadas com abas e widgets |
Estrutura do projeto
A ferramenta de scaffolding gera a seguinte estrutura de arquivos:
my-twenty-app/
package.json
yarn.lock
.gitignore
.nvmrc
.yarnrc.yml
.oxlintrc.json
tsconfig.json
tsconfig.spec.json # TypeScript config for tests
vitest.config.ts # Vitest test runner configuration
LLMS.md
README.md
.github/
└── workflows/
└── ci.yml # GitHub Actions CI workflow
public/ # Public assets (images, fonts, etc.)
src/
├── application-config.ts # Required — main application configuration
├── default-role.ts # Default role for logic functions
├── constants/
│ └── universal-identifiers.ts # Auto-generated UUIDs and app metadata
└── __tests__/
├── setup-test.ts # Test setup (server health check, config)
└── app-install.integration-test.ts # Integration test
Começando a partir de um exemplo
Para começar a partir de um exemplo mais completo com objetos, campos, funções de lógica, componentes de front-end e mais, use a opção --example:
npx create-twenty-app@latest my-twenty-app --example postcard
yarn twenty add (veja Criando aplicativos).
Arquivos principais
| Arquivo / Pasta | Finalidade |
|---|
package.json | Declara o nome, a versão e as dependências do seu aplicativo. Inclui um script twenty para que você possa executar yarn twenty help e ver todos os comandos. |
src/application-config.ts | Obrigatório. O principal arquivo de configuração do seu aplicativo. |
src/default-role.ts | Papel padrão que controla o que suas funções de lógica podem acessar. |
src/constants/universal-identifiers.ts | UUIDs gerados automaticamente e metadados do aplicativo (nome de exibição, descrição). |
src/__tests__/ | Testes de integração (configuração + teste de exemplo). |
public/ | Recursos estáticos (imagens, fontes) servidos com seu aplicativo. |
Servidor de desenvolvimento local
A ferramenta de scaffolding já iniciou um servidor local do Twenty para você. Para gerenciá-lo depois, use yarn twenty server:
| Comando | Descrição |
|---|
yarn twenty server start | Inicia o servidor local (baixa a imagem se necessário) |
yarn twenty server start --port 3030 | Iniciar em uma porta personalizada |
yarn twenty server stop | Interrompe o servidor (preserva os dados) |
yarn twenty server status | Mostra o status do servidor, a URL e as credenciais |
yarn twenty server logs | Transmite os logs do servidor |
yarn twenty server logs --lines 100 | Mostra as últimas 100 linhas de log |
yarn twenty server reset | Exclui todos os dados e inicia do zero |
twenty-app-dev-data para PostgreSQL, twenty-app-dev-storage para arquivos). Use reset para apagar tudo e começar do zero.
O servidor requer que o Docker esteja em execução. Se você vir um erro “Docker not running”, certifique-se de que o Docker Desktop (ou o daemon do Docker) esteja iniciado.
Configuração manual (sem o gerador)
Se preferir configurar tudo por conta própria em vez de usar create-twenty-app, você pode fazer isso em duas etapas.
1. Adicione twenty-sdk e twenty-client-sdk como dependências:
yarn add twenty-sdk twenty-client-sdk
twenty ao seu package.json:
{
"scripts": {
"twenty": "twenty"
}
}
yarn twenty dev, yarn twenty help e todos os outros comandos.
Não instale o twenty-sdk globalmente. Use-o sempre como uma dependência local do projeto para que cada projeto possa fixar sua própria versão.
Resolução de Problemas
Se você tiver problemas:
- Certifique-se de que o Docker está em execução antes de iniciar o scaffolder com uma instância local.
- Certifique-se de que está usando Node.js 24+ (
node -v para verificar).
- Certifique-se de que o Corepack está ativado (
corepack enable) para que o Yarn 4 esteja disponível.
- Tente excluir
node_modules e executar yarn install novamente se as dependências parecerem corrompidas.
Ainda com dificuldades? Peça ajuda no Discord da Twenty.
