Git workflow para TypeScript: como não enlouquecer com código tipado

Git workflow para TypeScript: como parar de ter medo de merge conflict

Se você já tentou mesclar duas branches onde uma alterava a interface User e a outra adicionava um novo tipo no mesmo módulo, você sabe o que é uma crise existencial de desenvolvedor. TypeScript nos dá um poderoso sistema de tipos, mas sem um Git workflow adequado, esse poder se transforma em dor de cabeça.

Neste artigo, vamos analisar o Git workflow ideal para projetos TypeScript — desde a configuração de branches até a verificação automática de tipos a cada commit. Sem enrolação, apenas o que realmente funciona na prática.

Por que o TypeScript exige uma abordagem especial para Git?

TypeScript não é apenas "JavaScript com tipos". É uma linguagem onde cada alteração pode afetar dezenas de arquivos através de interface, type e genéricos. Uma pequena correção errada em um tipo base — e todo o projeto para de compilar.

Portanto, um git workflow padrão para TypeScript deve incluir:

\n
• Verificação obrigatória de tipos antes do commit
\n
• Linter que impede o commit de código não formatado
\n
• Estratégia clara de branching para que merge conflicts não quebrem os tipos
\n
• CI/CD que verifica tudo novamente no servidor
\n

Vamos analisar cada item em ordem.

1. Escolhendo a estratégia de branching: Git Flow ou Trunk-based?

Para projetos TypeScript, recomendo o Trunk-based development com branches de curta duração. Por quê? Porque o código TypeScript é, essencialmente, código "bruto" que precisa ser verificado e implantado rapidamente. Branches longas fazem com que os tipos "divergem".

Estrutura básica de branches

main        — versão estável, sempre pronta para deploy\ndevelop     — branch principal de desenvolvimento\nfeature/*   — novas funcionalidades (vivem 1-2 dias)\nfix/*       — correções de bugs\nrelease/*   — preparação de release (opcional)\n

Exemplo para um projeto TypeScript:

git checkout -b feature/add-user-validation\n# trabalhando...\ngit commit -m "feat: add email validation for User type"\ngit push origin feature/add-user-validation\n# criando PR → merge em develop\n

Importante: nunca faça rebase na main se o projeto tiver tipos compartilhados. Use merge — ele preserva o histórico e não quebra dependências.

2. Git Hooks: proteção contra idiotas (e contra você mesmo)

O cenário mais comum: você esqueceu de executar tsc, fez commit, fez push, e o CI falhou. Para evitar isso, configuramos pre-commit hooks.

Instalação do Husky + lint-staged

Husky é uma ferramenta para gerenciar Git hooks. lint-staged executa comandos apenas nos arquivos modificados.

npm install --save-dev husky lint-staged\nnpx husky init\n

Crie o arquivo .husky/pre-commit:

#!/usr/bin/env sh\n. "$(dirname -- "$0")/_/husky.sh"\n\nnpx lint-staged\n

No package.json, adicione:

{\n  "lint-staged": {\n    "*.ts": [\n      "eslint --fix",\n      "prettier --write",\n      "tsc --noEmit"\n    ]\n  }\n}\n

Agora, antes de cada commit:

\n
1. ESLint é executado com autofix
\n
2. O código é formatado com Prettier
\n
3. A compilação TypeScript é verificada (tsc --noEmit)
\n

Se qualquer etapa falhar — o commit não passará. Cruel, mas eficaz.

3. Mensagens de commit corretas: conventional commits

Projetos TypeScript se beneficiam de conventional commits, porque:

\n
• O changelog é gerado automaticamente
\n
• É fácil entender quais alterações quebram tipos
\n
• É possível acionar o CI apenas para commits específicos
\n

Exemplos:

feat: add UserRole enum and validation\nfix: c