ADR-0002 Framework de aplicação

Contexto

O React (ADR-0001) é uma biblioteca de UI, não um framework full-stack. Precisamos de routing, SSR/streaming, server functions, carregamento de dados e tooling de build como uma única camada coerente. Esta escolha condiciona o destino de deploy (ADR-0003) e tudo o que vem depois.

Opções consideradas

1. TanStack Start

Framework React full-stack da equipa TanStack, construído sobre o TanStack Router (routing com tipagem segura) e o Vite. Server functions, SSR com streaming, adaptadores para deploy em qualquer ambiente.

Prós

• Type-safe de ponta a ponta: rotas, parâmetros, parâmetros de pesquisa, server functions — o TypeScript flui por tudo
• Deploy independente da plataforma: Vercel, Cloudflare, Node/Docker — sem lock-in
• Baseado em Vite: desenvolvimento rápido, output de build standard
• As server functions são RPC tipado simples — na maioria das apps não é preciso uma camada de API separada
• Alinha com o ecossistema TanStack (Query, Table, Form) que podemos adotar aos poucos mais tarde

Contras

• Mais recente do que o Next.js; comunidade mais pequena, menos respostas no Stack Overflow
• A superfície da API mudou depressa antes da 1.0 (estável desde 2026-10-13, APIs agora com garantia de estabilidade)
• Menos acompanhamento; ficam a nosso cargo mais decisões de arquitetura

2. Next.js

O meta-framework React dominante.

Prós

• O maior ecossistema e comunidade; cada problema tem um tutorial
• O deploy na Vercel é sem atritos
• Server components e caching são poderosos em escala

Contras

• Moldado pela Vercel: o self-hosting funciona, mas é tratado como secundário; entra em conflito com o nosso destino de deploy em Docker (ADR-0003)
• A semântica de caching é cada vez mais complexa e surpreendente
• As constantes mudanças no App Router têm saído caras às equipas

3. Remix / React Router v7

Framework React focado no carregamento de dados, agora integrado no React Router v7.

Prós

• Excelente modelo de carregamento de dados (loaders/actions)
• Deploy em qualquer ambiente, baseado em standards (web fetch API)
• Estável, sem surpresas, previsível

Contras

• Proposta de type-safety mais fraca do que a do TanStack Start
• A direção futura foi absorvida pelo React Router; a identidade “Remix” está a esbater-se
• Menor notoriedade do que o Next.js

Decisão

O TanStack Start é o framework full-stack padrão da empresa para todas as novas apps React.

Os fatores decisivos: type safety de ponta a ponta, adaptadores de deploy para qualquer ambiente (funciona com o nosso destino Docker, ADR-0003), tooling Vite e server functions tipadas que eliminam uma camada de API separada na maioria das apps. Aceitamos a comunidade mais pequena em troca da melhor experiência de TypeScript no ecossistema React.

Consequências

Mais fácil: routing e fluxo de dados com tipagem segura, flexibilidade de deploy, adoção incremental do TanStack Query/Table/Form.

Mais difícil: menos respostas prontas a copiar do que no Next.js; a equipa tem de se sentir à vontade a ler a documentação e o código-fonte do TanStack. As triagens de recrutamento devem avaliar a profundidade em TypeScript, não a experiência com Next.js.

Do que abdicamos: do peso do ecossistema do Next.js e dos deploys sem atritos da Vercel. Aceite — a flexibilidade de deploy e a type safety importam-nos mais.