Ir para o conteúdo
Promovaweb

Ferramentas para desenvolver com Astro

O editor, o terminal e os agentes que entram no dia a dia de um projeto Astro. No site da Promovaweb, o Codex e o Claude Code editam páginas e artigos direto no repositório.

VS Code

Configure o VS Code para o Astro com a extensão oficial: realce de sintaxe, informação de tipos e IntelliSense nos arquivos .astro. Veja a instalação.

Um arquivo .astro aberto num editor sem suporte à linguagem aparece como texto corrido. O frontmatter, o HTML e as expressões entre chaves ficam da mesma cor. Nada avisa quando uma prop chega com o tipo errado. A documentação do Astro recomenda o VS Code com a extensão oficial para ler esse arquivo. O VS Code é o editor de código da Microsoft, roda em Windows, macOS e Linux e entende JavaScript, TypeScript, HTML e CSS sem extensões.

O VS Code no Astro

A documentação do Astro indica o VS Code como o editor recomendado para projetos do framework. O projeto mantém a extensão oficial do Astro, publicada como astro-build.astro-vscode no marketplace. Com a extensão instalada, o editor oferece realce de sintaxe para arquivos .astro, informação de tipos TypeScript e IntelliSense para completar código e mostrar dicas enquanto você escreve. A extensão também inclui a formatação com Prettier dentro do editor. O Astro funciona com qualquer editor, então o VS Code é uma escolha, não uma exigência.

Instalar a extensão do Astro no VS Code

Instale a extensão oficial do Astro no VS Code para realçar o arquivo .astro e ver os tipos enquanto escreve. O guia de configuração de editor do Astro mostra o identificador da extensão e os recursos que ela acrescenta.

Herdr

Organize o astro dev, o agente de programação e o build em abas e painéis do Herdr, com os terminais rodando no Herdr Core quando o aplicativo fecha.

Num projeto Astro com agente de programação, você mantém três terminais abertos ao mesmo tempo. Um roda o astro dev, outro roda o agente que edita os arquivos e o terceiro fica para o build e o Git. Fechar a janela errada derruba o servidor no meio da tarefa. O Herdr separa esses terminais em espaços, abas e painéis. No Herdr Desktop, o Herdr Core mantém cada terminal rodando mesmo quando você fecha o aplicativo.

Como ele entra num projeto Astro

O Herdr não tem integração própria com o Astro. Ele roda terminais comuns. Você abre um painel no diretório do projeto e usa os comandos do próprio Astro:

Terminal
npm run dev
npm run build

Um espaço pode corresponder ao repositório do site, com uma aba por tarefa. Num painel fica o servidor de desenvolvimento, no outro o agente. O Herdr reconhece os agentes de programação que rodam nos painéis e mostra se cada um está trabalhando, concluiu ou espera uma resposta sua.

O Herdr vem em duas edições. O Herdr TUI roda dentro do terminal. O Herdr Desktop é o aplicativo de janela e usa o Herdr Core para manter os terminais.

Rodar o astro dev e o agente em painéis

Abra o painel no diretório do seu site e rode o astro dev em uma aba e o agente em outra para manter o servidor vivo durante a edição. O site do Herdr mostra a organização em abas e painéis. O repositório guarda o código do aplicativo.

Claude Code

Ligue o Claude Code ao servidor MCP da documentação do Astro e deixe o agente editar as páginas e os artigos do site com a referência oficial ao lado.

O Claude Code é o outro agente que edita o site da Promovaweb. Ele trabalha nos mesmos arquivos de Markdown e JSON do repositório, roda o build e mostra o que vai alterar antes de gravar. O Claude Code é o agente de programação da Anthropic e roda no terminal, nas extensões para VS Code e JetBrains e no navegador.

O Claude Code no Astro

O guia de construção com IA do Astro mostra como ligar o Claude Code ao servidor MCP da documentação. O comando claude mcp add –transport http astro-docs https://mcp.docs.astro.build/mcp registra o servidor, que entrega a documentação atual ao agente. Existe também uma ação do GitHub que responde a eventos do repositório e consulta a mesma documentação. Com a ligação ativa, o Claude Code gera código Astro apoiado na referência oficial.

Conectar o Claude Code ao servidor MCP do Astro

Registre o servidor MCP da documentação no Claude Code para gerar código do seu site com a referência oficial ao lado. O guia Build with AI mostra o comando e o endereço do servidor.

Codex

Ligue o Codex CLI ao servidor MCP da documentação do Astro e deixe o agente editar as páginas e os artigos do site com a referência oficial ao lado.

No site da Promovaweb, o Codex edita páginas e artigos direto nos arquivos do repositório. Esse foi um dos motivos da migração do site para o Astro: o conteúdo em Markdown e JSON fica ao alcance do agente, junto do código. O Codex é o agente de programação da OpenAI e roda no terminal pelo Codex CLI, na extensão de IDE e no Codex Cloud.

O Codex no Astro

O guia de construção com IA do Astro descreve como ligar o Codex CLI ao servidor MCP da documentação. O servidor fica em https://mcp.docs.astro.build/mcp e entrega a documentação atual ao agente. Você configura o servidor no arquivo ~/.codex/config.toml ou em um arquivo .codex/config.toml na raiz do projeto. Com essa ligação, o Codex consulta a documentação oficial enquanto gera código Astro. Quando o Astro detecta um agente de programação, o astro dev inicia o servidor em segundo plano no macOS e no Linux.

Conectar o Codex ao servidor MCP do Astro

Registre o servidor MCP da documentação no arquivo de configuração do Codex para consultar a referência oficial enquanto o agente edita o site. O guia Build with AI mostra o endereço do servidor e a configuração no config.toml.

GitHub

Guarde o histórico das páginas e artigos do seu site Astro no GitHub, revise mudanças por pull request e publique com a ação oficial no GitHub Pages.

Num site Astro, páginas e artigos são arquivos. Sem um repositório, você perde o histórico de cada alteração e não tem como recuperar um post apagado por engano. O GitHub guarda esse histórico, mostra o que mudou em cada commit e ainda publica o site a cada push. Com um pull request, você propõe uma mudança e revisa antes de juntar ao site. O GitHub Actions roda o build e a publicação a cada push.

O GitHub no Astro

A documentação do Astro mantém um guia para publicar um site pré-renderizado no GitHub Pages. O projeto oferece a ação oficial withastro/action, que instala as dependências, gera o build e envia o site. No astro.config.mjs você define o campo site com a URL do GitHub e o campo base com o nome do repositório. Com a fonte configurada para GitHub Actions na seção Pages, cada push para a branch principal publica o site.

Publicar o site no GitHub Pages

Configure a ação oficial do Astro para publicar o site a cada push para a branch principal. O guia Deploy to GitHub Pages mostra o arquivo de workflow e os campos site e base no astro.config.mjs.

Cloudflare

Publique um blog ou uma landing page em Astro na Cloudflare com a Wrangler CLI e use o adapter oficial quando houver rotas sob demanda no projeto.

O site da Promovaweb roda na Cloudflare. A plataforma serve o HTML estático do build e também roda as rotas renderizadas sob demanda quando o projeto usa o adapter. A documentação do Astro recomenda o Cloudflare Workers para projetos novos e mantém um guia de deploy próprio.

O Cloudflare no Astro

O guia de deploy do Astro usa a Wrangler CLI para compilar e publicar o site. O comando npx astro build && npx wrangler deploy gera o build e envia os arquivos.

Para rotas renderizadas sob demanda, o comando npx astro add cloudflare instala o adapter @astrojs/cloudflare e ajusta o astro.config.mjs. O Wrangler oferece um preview local com npx astro build && npx wrangler dev para conferir o site.

Para publicar a cada push, você usa um sistema de CI/CD como o Workers Builds, que importa o repositório, roda o build e envia o site.

Publicar o site na Cloudflare com a Wrangler

Publique o build do seu site com a Wrangler CLI para ver as páginas no ar. O guia Deploy to Cloudflare mostra o comando npx astro build && npx wrangler deploy e a instalação do adapter quando o projeto usa rotas sob demanda.

Lighthouse

Meça performance, acessibilidade e SEO do site Astro antes de publicar com o Lighthouse do Chrome DevTools e leia o motivo de cada item apontado.

O PageSpeed Insights mede a página já publicada. Para medir antes de publicar, no seu computador e no build local, você usa o Lighthouse, que já vem no Chrome. O Lighthouse é a ferramenta open source do Google que audita a página. Cada item apontado no relatório traz o motivo do problema e o caminho da correção.

O Lighthouse no Astro

O Lighthouse fica num painel próprio do Chrome DevTools. Você abre a página do site, incluindo um site feito com Astro. A auditoria começa pela aba Lighthouse. A ferramenta também roda pela linha de comando e como módulo Node. O PageSpeed Insights usa o Lighthouse para a medição de laboratório. O Lighthouse CI confere a qualidade a cada mudança e aponta quando uma métrica piora.

Medir o site local antes de publicar

Rode a auditoria no Chrome DevTools para medir o site local e ler o motivo de cada item apontado. A visão geral do Lighthouse mostra os fluxos no painel, na linha de comando e no Lighthouse CI.

PageSpeed Insights

Meça o site Astro no PageSpeed Insights em mobile e desktop e veja o que pesa no carregamento. A Promovaweb saiu da migração com 40 no mobile. Leia o caso.

Depois da migração do site da Promovaweb para o Astro, a nota mobile no PageSpeed Insights ficou em 40. A troca de framework não corrigiu a página sozinha. A correção veio depois, numa intervenção com o Claude, que levou a versão desktop a 100. A nota de uma página publicada depende das imagens, das fontes e do JavaScript que você coloca nela. Trocar o framework deixa esses três pontos como estavam. O PageSpeed Insights é o serviço do Google que mede uma página em mobile e em desktop. O relatório mostra o que pesa no carregamento.

O PageSpeed Insights no Astro

O serviço não tem integração específica com o Astro. Você cola a URL pública do site no campo e o PageSpeed analisa a página, incluindo projetos feitos com Astro. A análise de campo cobre as métricas First Contentful Paint, Largest Contentful Paint, Interaction to Next Paint e Cumulative Layout Shift. O Time to First Byte entra como métrica experimental. Uma nota de 90 ou mais é considerada boa na medição de laboratório. Para uma página nova, o serviço pode recorrer à granularidade de origem quando não há amostras suficientes.

Medir a URL publicada no PageSpeed Insights

Cole a URL pública do seu site no campo do PageSpeed Insights para ver a nota em mobile e desktop. A ferramenta fica em pagespeed.web.dev. A documentação explica as faixas de nota e as métricas.

StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.