Pré-requisitos
- Node.js 24+ — Baixar
- Yarn 4 — Vem com o Node.js via Corepack. Ative-o:
corepack enable
- Docker — Baixar. Necessário para executar um servidor Twenty local. Ignore se você já tiver o Twenty em execução em outro lugar.
A criação de um aplicativo Twenty tem três fases. A ferramenta de scaffolding as reúne em um único comando do fluxo ideal, mas cada fase é um conceito separado — quando algo falha, saber em que fase você está indica o que corrigir.
| Fase | O que você faz | Ferramenta | Resultado |
|---|
| 1. Criar scaffolding | Gerar o código-fonte do aplicativo | npx create-twenty-app | Um projeto TypeScript em disco |
| 2. Executar um servidor | Iniciar um servidor Twenty para o qual sincronizar | Docker + yarn twenty server | Uma instância Twenty em execução |
| 3. Sincronizar | Sincronize seu código em tempo real com o servidor | yarn twenty dev | Suas alterações aparecem na interface |
Fase 1 — Fazer scaffolding do seu projeto
Crie um novo aplicativo a partir do modelo:
npx create-twenty-app@latest my-twenty-app
my-twenty-app/ com um application-config.ts inicial, um papel padrão, um fluxo de trabalho de CI e um teste de integração.
Após esta fase: você tem o código-fonte de um aplicativo na sua máquina. Ele ainda não está em execução — isso é a Fase 2.
Fase 2 — Executar um servidor Twenty local
Seu aplicativo precisa de um servidor Twenty para o qual sincronizar. O servidor é uma instância completa do Twenty — interface, API GraphQL, PostgreSQL — executando localmente no Docker. Seu código local envia suas definições para esse servidor, o que faz com que elas apareçam na interface.
A ferramenta de scaffolding oferece iniciar um para você:
Você gostaria de configurar uma instância local do Twenty?
- Sim (recomendado) — baixa a imagem Docker
twentycrm/twenty-app-dev e a inicia na porta 2020. Certifique-se de que o Docker esteja em execução primeiro.
- Não — escolha isto se você já tiver um servidor Twenty ao qual deseja se conectar. Você pode conectá-lo depois com
yarn twenty remote add.
Quando o servidor estiver ativo, um navegador será aberto para login. Use a conta de demonstração pré-configurada:
- E-mail:
tim@apple.dev
- Senha:
tim@apple.dev
Clique em Authorize na próxima tela — isso dá à CLI acesso ao seu espaço de trabalho.
Seu terminal confirmará que tudo está configurado.
Após esta fase: você tem um servidor Twenty em execução em http://localhost:2020 com sua CLI autorizada a sincronizar com ele.
Se o Docker não estiver instalado ou em execução, a ferramenta de scaffolding informará o comando de inicialização correto para o seu sistema operacional. Quando o Docker estiver ativo, você pode retomar com yarn twenty server start — sem necessidade de recriar o scaffolding.
Fase 3 — Sincronizar suas alterações
Este é o ciclo interno no qual você passará a maior parte do tempo.
cd my-twenty-app
yarn twenty dev
src/, recompila a cada alteração e sincroniza o resultado com o servidor. Edite um arquivo, salve e, em um segundo, o servidor refletirá a alteração. Você verá um painel de status em tempo real no seu terminal.
Para uma saída mais detalhada (logs de build, solicitações de sincronização, rastros de erro), adicione --verbose.
Abra http://localhost:2020/settings/applications#developer. Você deverá ver seu aplicativo em Your Apps.
Clique em My twenty app para ver seu registro do aplicativo — um registro em nível de servidor que descreve seu aplicativo (nome, identificador, credenciais OAuth, origem). Um registro pode ser instalado em vários espaços de trabalho no mesmo servidor.
Clique em View installed app para ver a instalação no espaço de trabalho. A aba About mostra a versão e as opções de gerenciamento.
Após esta fase: você tem um ciclo de desenvolvimento em tempo real. Edite qualquer arquivo em src/ e ele aparecerá na interface.
Sincronização única para CI e scripts
Passe --once para executar uma única compilação + sincronização e sair — mesmo pipeline, sem watcher:
| Comando | Comportamento | Quando usar |
|---|
yarn twenty dev | Monitora e ressincroniza a cada alteração. Fica em execução até você interrompê-lo. | Desenvolvimento local interativo. |
yarn twenty dev --once | Executa uma única compilação + sincronização e, em seguida, encerra com o código 0 em caso de sucesso ou 1 em caso de falha. | Scripts, CI, hooks de pre-commit, agentes de IA e fluxos de trabalho com script. |
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 implantar em servidores de produção. Veja Publicação de aplicativos.
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 | Modelos de dados personalizados (Cartão postal, Fatura etc.) 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 |
| Layouts de página | Páginas de detalhes de registros personalizadas com abas e widgets |
Estrutura do projeto
my-twenty-app/
package.json
src/
application-config.ts # Required — your app's entry point
default-role.ts # Permissions for logic functions
constants/
universal-identifiers.ts # Auto-generated UUIDs and metadata
__tests__/
setup-test.ts
app-install.integration-test.ts
.github/workflows/ci.yml # GitHub Actions
public/ # Static assets
vitest.config.ts # Test runner config
tsconfig.json, tsconfig.spec.json
.nvmrc, .yarnrc.yml, .oxlintrc.json
README.md, LLMS.md
| Arquivo / Pasta | Finalidade |
|---|
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 (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. |
Começando a partir de um exemplo
Use --example para começar com um projeto mais completo (objetos personalizados, campos, funções de lógica, componentes de front-end):
npx create-twenty-app@latest my-twenty-app --example postcard
yarn twenty add — veja Criando aplicativos.
Gerenciando o servidor local
Use yarn twenty server para controlar o contêiner Twenty local:
| Comando | O que faz |
|---|
yarn twenty server start | Inicia o servidor (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 a URL, a versão e as credenciais de login |
yarn twenty server logs | Transmite os logs do servidor |
yarn twenty server reset | Apaga os dados e começa do zero |
yarn twenty server upgrade | Baixa a imagem mais recente twenty-app-dev |
yarn twenty server upgrade 2.2.0 | Atualizar para uma versão específica |
twenty-app-dev-data para PostgreSQL, twenty-app-dev-storage para arquivos). Use reset para apagar tudo.
Atualizando a imagem do servidor
yarn twenty server upgrade baixa a imagem mais recente, compara os digests e só recria o contêiner se algo realmente tiver mudado. Os volumes são preservados — apenas o contêiner é substituído. Se uma nova imagem foi baixada e o contêiner estava em execução, a atualização inicia automaticamente um novo contêiner; execute yarn twenty server start depois para aguardar até que ele fique saudável.
yarn twenty server upgrade # Latest
yarn twenty server upgrade 2.2.0 # Specific version
yarn twenty server status (ele mostra o APP_VERSION incorporado ao contêiner).
Executando uma instância de teste paralela
Passe --test para qualquer comando de server para gerenciar uma segunda instância totalmente isolada — útil para testes de integração ou para experimentar sem tocar nos seus dados principais de desenvolvimento:
| Comando | O que faz |
|---|
yarn twenty server start --test | Inicia a instância de teste (padrão: porta 2021) |
yarn twenty server stop --test | Parar |
yarn twenty server status --test | Mostrar seu status |
yarn twenty server logs --test | Transmitir seus logs |
yarn twenty server reset --test | Apagar seus dados |
yarn twenty server upgrade --test | Atualizar sua imagem |
twenty-app-dev-test), volumes (twenty-app-dev-test-data, twenty-app-dev-test-storage) e configuração — ela é executada junto com sua instância principal sem conflitos. Combine --test com --port para substituir 2021.
Configuração manual (sem o gerador)
Ignore a ferramenta de scaffolding se você estiver adicionando o SDK a um projeto existente:
yarn add twenty-sdk twenty-client-sdk
package.json:
{
"scripts": {
"twenty": "twenty"
}
}
yarn twenty dev, yarn twenty server start e o restante.
Não instale twenty-sdk globalmente — fixe-o por projeto, para que cada aplicativo use sua própria versão.
Resolução de Problemas
- Erros do Docker — Certifique-se de que o Docker Desktop (ou o daemon) esteja em execução antes de
yarn twenty server start. A mensagem de erro mostrará o comando de inicialização correto para o seu sistema operacional.
- Versão errada do Node — É necessário 24 ou superior. Verifique com
node -v.
- Falta o Yarn 4 — Execute
corepack enable.
- Dependências com problemas —
rm -rf node_modules && yarn install.
Travou? Peça ajuda no Discord da Twenty.
