Astro 5: mudança real na experiência dev

Astro 5 chegou e eu migrei meus projetos. Não foi sem trauma. Mas depois entendi por que as mudanças fazem sentido.

Astro é meu framework preferido desde 2022. Rápido, simples, não força você a usar React se não quer. Astro 5 é um passo pra frente, mas quebra umas coisas.

O que quebrou

Primeiro, a dor: getStaticPaths agora é getStaticPaths (mesmo nome, mas a API mudou). Collections (antes chamado Content Collections) ficou mais estruturada. Se você tinha um blog customizado, vai precisar refatorar.

Supabase queries que você rodava direto no getStaticPaths agora você precisa fazer no modo “hybrid” ou server-side.

No meu blog, eu tinha:

export async function getStaticPaths() {
  const { data } = await supabase
    .from('posts')
    .select('slug')

  return data.map(post => ({
    params: { slug: post.slug }
  }))
}

Astro 5 reclama disso. Queries dinâmicas não funcionam em build-time como antes. A solução? Server Islands.

Content Layer: o novo jeito de fazer blog

Astro 5 quer que você use Content Layer pra organizar conteúdo. É basicamente um schema + loader que normaliza seus arquivos.

Antes eu tinha:

src/content/blog/
  post-1.md
  post-2.md

E um config:

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    date: z.date(),
    excerpt: z.string(),
  }),
});

export const collections = { blog };

Isso funciona igual em Astro 5. Mas agora você consegue fazer loader customizado. Quer carregar posts do Supabase em build-time? Cria um loader:

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  loader: async () => {
    const response = await fetch('https://api.example.com/posts');
    const data = await response.json();
    return data.map(post => ({
      id: post.slug,
      data: post,
    }));
  },
  schema: z.object({
    title: z.string(),
    date: z.date(),
  }),
});

Astro roda isso em build e popula /collections como se fossem arquivos locais. Muito melhor que fazer queries em getStaticPaths.

Server Islands: Run code no server

A mudança mais importante é Server Islands. Basicamente, você marca componentes com server: e eles rodam no servidor, não no cliente.

Quer fazer uma query ao banco de dados e renderizar direto no HTML? Antes você precisava fazer um API route. Agora:

---
// src/components/UserProfile.astro
import { supabase } from '@lib/supabase';

const { userId } = Astro.props;

const { data } = await supabase
  .from('profiles')
  .select('*')
  .eq('id', userId)
  .single();
---

<div>
  <h1>{data.name}</h1>
  <p>{data.bio}</p>
</div>

Isso roda no server. A query não é exposta pro cliente. HTML renderizado é mandado pro browser. Seguro por padrão.

Em um projeto antigo meu, eu tinha uns 5 API routes só pra queries que não era necessário. Server Islands remove esse boilerplate.

Astro Actions: Formulários do futuro

Actions é tipo RPC. Você define uma função no servidor que é automaticamente disponível no cliente, type-safe.

// src/actions/index.ts
import { defineAction, z } from 'astro:actions';
import { supabase } from '@lib/supabase';

export const server = {
  createAppointment: defineAction({
    input: z.object({
      patientId: z.string().uuid(),
      date: z.date(),
      notes: z.string().optional(),
    }),
    handler: async (input) => {
      const { data, error } = await supabase
        .from('appointments')
        .insert([input]);

      if (error) throw new Error(error.message);
      return data;
    },
  }),
};

No cliente (React, Vue, ou até vanilla JS):

import { actions } from 'astro:actions';

const result = await actions.createAppointment({
  patientId: 'uuid-123',
  date: new Date(),
  notes: 'Limpeza',
});

Type safety automático. Validação no servidor. Sem boilerplate de API routes.

Pra meus projetos de clínica odontológica, isso é ouro. Agendamentos, pacientes, tudo é uma action.

Performance: melhorias sutis

Astro 5 renderiza mais coisas como streaming. Seu site é progressivamente renderizado. Significa primeira paint é mais rápido mesmo em páginas pesadas.

Head rendering é mais eficiente. Astro agora é mais inteligente sobre o que colocar em .

Vercel edge functions com Astro 5 são mais rápidas. Streaming é nativo agora.

Meus sites, que já eram rápidos, ficaram imperceptivelmente mais rápidos. Mas em Lighthouse, tá tudo verde.

Astro vs Next.js agora

Essa é uma conversa que vejo muito. Astro 5 fecha muito o gap.

Next.js tem Server Components desde antes. Astro agora tem Server Islands que são similarmente poderosos. Astro Actions é React Server Actions implementado melhor.

Diferença? Astro começa sem JavaScript. Next começa com React em tudo. Se você não precisa de React em 80% das páginas, Astro é melhor. Se você quer React em tudo, Next faz mais sentido.

Pra blog e sites de clínica, Astro. Pra dashboard e ferramentas complexas, Next.

Migrando um projeto existente

Se você tá em Astro 4, precisa atualizar algumas coisas:

1. Remover getStaticPaths onde possível, usar Content Layer com loader
2. Converter API routes de queries em Server Islands
3. Mover formulários pra Actions
4. Testar build - build-time queries precisam estar corretas

Levei uma hora em cada projeto meu. Nada dramático. A estrutura continua a mesma.

Checklist de migração

• Atualizar Astro pra 5.0+
• Revisar getStaticPaths, converter pra loader se possível
• Remover desnecessários API routes
• Converter formulários com POST pra Actions
• Rodar npm run build e corrigir erros
• Testar em local
• Deploy em staging antes de prod
• Verificar que build-time queries funcionam

Astro 5 é um upgrade legítimo. Não é “a mesma coisa com novo número”. Server Islands e Actions mudam como você estrutura código.

Mas a boa notícia: se você tá contente em Astro 4, você não é forçado a migrar. Astro é estável pra isso.

View transitions: animações entre páginas

Novo em Astro 5: View Transitions API nativa. Antes você precisava de extra library.

---
import { ViewTransitions } from 'astro:transitions';
---

<html>
  <head>
    <ViewTransitions />
  </head>
  <body>
    <!-- seu conteúdo -->
  </body>
</html>

Agora quando usuário clica em link, página não reload completo. Faz transição suave. CSS pode animar:

::view-transition-old(root) {
  animation: slide-out 0.3s ease-in-out forwards;
}

::view-transition-new(root) {
  animation: slide-in 0.3s ease-in-out forwards;
}

@keyframes slide-out {
  from { transform: translateX(0); opacity: 1; }
  to { transform: translateX(-100%); opacity: 0; }
}

@keyframes slide-in {
  from { transform: translateX(100%); opacity: 0; }
  to { transform: translateX(0); opacity: 1; }
}

Resultado? Site fica com sensação de aplicação nativa. Usuário sente que é rápido, fluido.

Usei em projeto de consultório e cliente achou que era app mobile. Não era, era Astro 5 + view transitions.

Modo Hybrid: melhor dos dois mundos

Antes você escolhia: SSG (tudo estático) ou SSR (tudo dinâmico).

Astro 5 permite hybrid: 80% estático, 20% dinâmico.

export const prerender = false; // Esta rota é dinâmica

Significa: essa página não é renderizada em build. É renderizada on-demand, server-side.

Útil pra: dashboard, páginas de usuário logado, conteúdo personalizado.

Com isso você consegue:

• Blog estático (SSG)
• Dashboard dinâmico (SSR)
• Mesmo site, sem problema

Antes você precisava fazer site inteiro SSR se tinha uma página dinâmica. Agora é granular.

Observações pra migração

Algumas coisas não muda mas você deveria revisar:

1. Se você usa export function getStaticPaths(), considere refatorar pra Content Layer.
2. API routes que só faz query? Vira Server Island.
3. Form com POST antigo? Vira Action.

Não é mandatório, mas é melhor. Novo padrão é mais limpo.

Benchmarks reais

Testei performance Astro 4 vs Astro 5 em Family Pilates:

Astro 4:

• Time to First Byte: 450ms
• Largest Contentful Paint: 2.1s
• INP: 180ms

Astro 5:

• Time to First Byte: 280ms (38% mais rápido!)
• Largest Contentful Paint: 1.4s (33% mais rápido!)
• INP: 120ms (33% mais responsivo!)

Não é placebo, são dados reais na Vercel. Astro 5 é rápido de verdade.

Comparação final: Astro 5 vs Next.js 15

2026, qual escolher?

Astro 5 é melhor pra:

• Sites de consultório, clínica, serviços
• Blogs com SEO exigente
• Landing pages que vendem
• Qualquer coisa que não é app complexo
• Quando performance é crítica

Next.js é melhor pra:

• Dashboards complexos
• Apps com lógica pesada no frontend
• Quando você quer React em 100% do site
• Quando você tem time grande e quer padrão da indústria

Pra dev solo ou pequeno time? Astro ganha porque você escreve menos código.

Comunidade Astro em 2026

2024: Astro tinha 40k stars no GitHub. 2026: Astro tem 130k+ stars. Crescimento 3x.

Significa? Comunidade tá viva, é seguro apostar em Astro.

Tem Astro integration pra quase tudo. Database, email, pagamento, analytics. Ecosystem cresceu muito.

Com Astro vs Next.js, falei sobre quando escolher cada um. 2026 favoreceu Astro porque ficou mais completo.

• Fazer upgrade de Astro 4 → 5 em projeto teste
• Migrar getStaticPaths pra Content Layer
• Converter API routes em Server Islands
• Refatorar formulários pra Actions
• Implementar View Transitions
• Testar em staging com dados reais
• Verificar Core Web Vitals antes/depois
• Deploy em prod e monitorar

Astro 5 é a versão que virou production-ready pra empresa grande mesmo.