Escolher a stack e projetar suas dependências

Trocar a base do site depois de vinte telas prontas custa reescrever quase tudo, por isso essa escolha vem antes do primeiro comando. Conteúdo que se lê pede Astro, aplicativo que se opera pede Next.js e arquivo que abre sozinho pede HTML puro.

A base é o framework, ou seja, a estrutura pronta que já resolve o trabalho repetido de todo site, como a planta e a fundação de uma casa. Você a escolhe pelo que a página faz, com o motivo por escrito.

Três coisas decidem a base: o que a página faz, quem vai cuidar dela e por quanto tempo. Um site escrito em HTML puro com JavaScript nativo já entrega filtro e clique. O framework compensa quando entram estado (o que a tela lembra, como o carrinho cheio), rotas (os endereços internos) e componentes (peças de tela reaproveitadas em vários lugares).

Responda então duas perguntas antes de decidir. A página precisa aparecer no Google e ser citada por assistente de IA, ou precisa abrir direto de um arquivo, sem servidor? E quanto JavaScript o celular do seu cliente aguenta sem travar? Quem mantém o site daqui a um ano fecha o critério.

Astro manda ao navegador uma página já montada em HTML e só liga JavaScript nos pedaços que você marcar, chamados de ilhas. Ligar uma ilha é hidratar, ou seja, dar movimento ao pedaço parado, como acender uma única televisão na vitrine em vez de todas.

Isso decide dinheiro porque cada trecho de JavaScript atrasa a abertura no celular, e página lenta perde a visita antes de ser lida. Por isso o Astro é a escolha para blog, documentação, site institucional, microsite e relatório estático, onde a pessoa lê e quase não opera nada.

O erro típico é marcar toda ilha para hidratar de imediato. O site volta a pesar como qualquer outro e você perde o motivo de ter escolhido o Astro. O catálogo de uma escola, que só lista curso, turma e matrícula, é o caso limpo: ali uma base de aplicativo cobraria servidor e manutenção que ninguém pediu.

Next.js existe para a outra metade do mundo: página com login, painel e dado que muda a cada minuto. Ele monta boa parte da tela no servidor e entrega pronta, então o navegador recebe menos trabalho e a pessoa vê o conteúdo antes.

A linha em uso aqui é a 16.3, que já vem com o Turbopack. Turbopack é o empacotador, o programa que junta os seus arquivos num pacote que o navegador entende, e esse junta rápido mesmo numa sessão longa de trabalho.

Por baixo roda o React, a biblioteca que desenha a tela em componentes. Uma falha de segurança registrada como CVE-2025-55182 atinge as versões 19.0.0 a 19.2.2 e pede correção nesta semana. CVE é o registro público de uma falha, com número, e o número é o que decide: acima da 19.2.2 você está fora dela.

As outras bases entram por um motivo prático: a equipe já as domina. Quem vem de um projeto React antigo segue no React Router. Quem já escreve em Svelte fica no SvelteKit, e quem tem time de Angular continua nele. Trocar de base para acompanhar novidade custa meses e não muda nada que o cliente veja.

Duas advertências de versão valem o espaço. Fique no HTMX 2.0.10, porque a linha 4.0 ainda em beta, ou seja, em teste aberto antes do lançamento, quebra o que já está no ar. A regra geral vem daí: versão marcada como beta ou como candidata a lançamento não entra em site de cliente, por melhor que pareça.

Custo de saída é o preço de abandonar uma tecnologia já construída, e quase ninguém calcula esse preço antes de escolher. As três bases montam a página de jeitos que não se traduzem entre si, então a conta não é trocar uma peça, e sim refazer o encaixe inteiro.

No Astro você decide ilha por ilha o que paga JavaScript. No Next.js você decide qual pedaço roda no servidor. Trocar depois de vinte telas prontas refaz onde o dado é buscado, onde o estado mora e qual arquivo manda em cada endereço. Proposta de troca sem o número de telas reescritas é proposta incompleta.

Quando site público e painel com login convivem, compare manter um projeto só com separar dois. Astro no público e Next.js no painel funciona bem, mas dobra a operação que alguém precisa cuidar. Se dividir, compartilhe o mesmo arquivo de tokens, que são cor e tipografia guardadas com nome, e escreva quem mantém cada publicação.

Crie o projeto já com TypeScript ligado e um arquivo de tokens antes da primeira tela. A partir daí, trocar a cor da marca no site inteiro passa a exigir uma linha só desse arquivo. Publique a primeira página num endereço público e confirme que o React instalado está acima da versão 19.2.2 antes de aprovar qualquer tela seguinte.

Saiba o que instalar em cada parte, e o que vem junto

A base do projeto está escolhida, e cada camada acima dela ainda pede uma peça padrão, um degrau sem biblioteca e a árvore de dependências conferida.

Um pacote instalado sem conferência pode carregar nome inventado pela IA e abrir uma porta de ataque no seu site. Pacote, ou biblioteca, é um pedaço de programa pronto que alguém publicou e você passa a usar dentro do seu.

Cada camada da tela tem uma peça padrão, e o que ela arrasta junto se confere antes de instalar. Agente é o assistente de IA que escreve o código. Quem aprova o que ele sugere decide a peça de cada camada e também o plano B sem instalar nada.

Seis camadas já têm dona, e saber o nome delas encurta reunião. A aplicação com login é Next.js e o conteúdo é Astro, a única camada em que trocar significa reescrever. O estilo é Tailwind, que descreve a aparência em pequenas marcações dentro da própria tela, em vez de num arquivo separado.

O componente vem do shadcn, copiado para dentro do projeto em vez de instalado, o que deixa você livre para alterá-lo. Teste cada um de novo com o teclado e com leitor de tela, porque acessibilidade que veio de fábrica costuma se perder na primeira alteração.

Ícone é Lucide, e só ele: misturar famílias de ícone faz a interface parecer montada por pessoas diferentes. O gráfico é Recharts, e painel com milhões de pontos pede ECharts. A loja que ia instalar três pacotes só para avisar pedido confirmado resolveu com um, o Sonner.

Acima delas ficam as utilidades de tela, e cada uma tem um degrau abaixo que resolve sem instalar nada. O nuqs guarda aba, filtro e paginação no próprio endereço da página. O teste é copiar o link e abrir em outra aba: se a tela volta diferente, o estado mora no lugar errado.

Lista comum serve até algumas centenas de itens; acima disso entra o TanStack Virtual, que desenha só as linhas visíveis. O cmdk, o Sonner e o Vaul entregam busca por comando, aviso de canto e gaveta inferior, e são o padrão de fato nesse conjunto de peças.

O Floating UI posiciona menu, dica e balão, e essa camada encolheu porque o próprio navegador passou a fazer parte do trabalho. Mantenha a biblioteca enquanto o seu painel de visitas mostrar navegador antigo, e garanta uma posição que continue legível quando o recurso novo for ignorado.

Já o number-flow anima um número dígito a dígito na direção certa, como o contador da bomba de combustível. Ele serve ao indicador que a diretoria acompanha ao vivo, porque o olho percebe a mudança antes mesmo de ler o valor.

Para tour de produto, o driver.js é leve e resolve a apresentação simples da tela a quem chega. O Shepherd.js cobre caminhos com desvio, mas a licença dele obriga a abrir o seu código ou pagar, e isso se lê antes de instalar. O auto-animate anima uma lista que reordena com uma linha.

O dado que vem do servidor e o estado que só existe na tela moram em lugares diferentes. Confundir os dois origina boa parte das telas que mostram número errado. TanStack Query ou SWR guardam a cópia do servidor em cache, a cópia local que evita pedir o mesmo dado de novo.

Zustand ou Jotai cuidam do estado leve da tela com pouco código. Redux Toolkit entra quando cada mudança precisa ficar registrada para auditoria, e cobra mais escrita justamente por isso. Para histórico que precisa sobreviver ao fechar da aba, o navegador tem banco próprio: mostre o dado de ontem e atualize por trás.

Tempo real começa pelo modo mais simples, o SSE: o servidor empurra e o navegador só ouve, como um rádio ligado. Isso cobre aviso, contador e acompanhamento de pedido, que é quase tudo o que um negócio pequeno precisa mostrar ao vivo.

WebSocket é a conversa nos dois sentidos e só entra quando a tela também precisa falar o tempo todo. Ele cobra atenção porque não segura fila sozinho: sem controle, o cliente lento acumula mensagens até travar. WebAssembly é acelerador cirúrgico, usado num cálculo pesado específico e nunca como substituto do frontend inteiro.

Toda biblioteca instalada traz outras dentro dela. A árvore final, que é a lista completa do que entrou junto, fica sempre maior que a lista que você escolheu. Rode npm ls --all e veja o tamanho real antes de confiar no que foi prometido.

Duas contas saem daí. A de licença: uma peça liberada pode arrastar outra restritiva e prender o seu código a condições que ninguém leu. A de segurança: cada peça é uma porta. Um modelo de IA inventa nome de pacote com confiança total, e existe ataque que registra esses nomes esperando quem instale sem olhar.

Antes de aceitar qualquer pacote sugerido, rode npm ls --all para ver a árvore inteira e npm audit para a lista de falhas conhecidas. Abra a página de cada um no registro npm e confirme duas coisas: lançamento recente e licença que permita uso comercial.

Pergunte antes de tudo isso, porém, se o navegador já resolve sozinho. Recursos que chegaram ao navegador nos últimos meses tiram bibliotecas inteiras da sua lista sem instalar nada, e essa é a economia mais barata que existe.

Guia prático: o que 51 sites profissionais usam de stack, e o que isso ensina

A pergunta "qual stack usar" tem resposta medida quando você olha o que gente que vende template escolheu. Nos 51 templates estudados em 07/10/2026, contando o package.json de cada um:

Para página de marketing que é uma tela só, Vite com React resolve, e ninguém ali precisou de servidor. A conta muda quando a página tem várias rotas. Dos 51, 30 usam BrowserRouter, que cria endereços como /cardapio. Num host estático, quem abre esse endereço direto ou recarrega a página recebe erro 404, porque o servidor procura um arquivo que não existe. Nenhum dos 51 usa HashRouter, e o CLAUDE.md de todos promete subir em qualquer host sem configuração extra.

A segunda lição está no que vem junto. Os templates em TypeScript carregam um pacote de componentes pronto, e a página usa 12 dos 53. Escolha a stack pelo que a página faz e conte o que você vai manter, não só o que vai usar hoje.

Guia prático: o que a stack de agosto a outubro de 2026 mudou para quem constrói com agente

A aula escolhe entre Astro e Next.js pelo que a página faz. De agosto a outubro, as duas bases ganharam funções que mudam o custo de manter: o Next.js passou a escrever no AGENTS.md (o arquivo de regras que o agente lê) o caminho da documentação da versão instalada, recomendou Cache Components para todo app e passou a reprovar o build quando um conteúdo dinâmico entra por acidente numa rota estática; o Astro agora reconstrói só as páginas que mudaram. Você sai daqui sabendo qual chave ligar em cada base e como provar que ela funcionou.

Aplicar os recursos ao projeto