Skip to main content

​
Pré-requisitos

  • Node.js 24.5+ — 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 1 — Fazer scaffolding do seu projeto

Crie um novo aplicativo a partir do modelo:
O gerador não é interativo: o nome do diretório se torna o nome do app. Passe --display-name e --description para personalizar os metadados gerados (você também pode editá-los depois em src/constants/universal-identifiers.ts). Isso gera um projeto TypeScript em my-twenty-app/ com um application-config.ts inicial, um papel padrão, fluxos de trabalho de CI/CD 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. O scaffolder inicia uma instância para você: com o Docker em execução, ele baixa a imagem twentycrm/twenty-app-dev, inicia-a na porta 2020 e autentica a CLI no workspace de demonstração pré-preenchido (tim@apple.dev) — sem necessidade de login. Para se conectar a um servidor Twenty existente em vez disso, passe --url \<your-server-url>. Servidores remotos se autenticam com OAuth: um navegador é aberto para que você faça login e clique em Authorize, o que dá à CLI acesso ao seu workspace. (Você também pode optar por usar OAuth localmente com --authentication-method oauth — faça login com tim@apple.dev / tim@apple.dev.)
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 docker: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.
Isso monitora src/, recompila a cada alteração e sincroniza o resultado com o servidor. Edite um arquivo, salve e, em alguns segundos, 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

Use plan e apply para executar o mesmo pipeline uma vez, sem watcher:
Todos os modos precisam de um remoto autenticado. Veja Sincronização e recuperação para mais detalhes sobre plan.
yarn twenty dev --once e yarn twenty dev --once --dry-run são aliases obsoletos para yarn twenty apply e yarn twenty plan.

​
Opções do modo de desenvolvimento

​
O que você pode criar

Os aplicativos são compostos por entidades — cada uma definida como um arquivo TypeScript com um único export default: Referência completa: Conceitos.

​
Próximos passos

Configuração

Identidade do aplicativo, função padrão, hooks de instalação e desinstalação, recursos públicos.

Data

Objetos, campos e relações bidirecionais.

Lógica

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

Layout

Exibições, navegação, layouts de página, componentes de front-end.

Operações

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