Site Astro através do Claude Code: da pasta à publicação

Até alguém que nunca escreveu uma linha de código pode criar um site com Astro através do Claude Code. Já deixei de escrever código à mão há muito tempo; faço tudo com palavras através da IA, e criar um site com Astro funciona exatamente da mesma forma: explica o que precisa e o Claude escreve o código por si.

O problema geralmente não está na criação do site em si, mas no facto de o percurso estar dividido em partes. Um artigo explica a instalação, outro aborda os comandos, um terceiro fala da publicação, e o percurso completo nunca se junta na sua cabeça. Aqui, levo-o de uma pasta vazia até um site acessível na Internet através de uma ligação: o que instalar, que comando usar para iniciar um projeto, como criar páginas através do Claude Code e como publicar o resultado gratuitamente. Baseio-me na documentação oficial do Astro.

Saiba mais sobre como trabalhar com o serviço na documentação do Ailoot.

O que precisa antes de começar?#

Não precisa de descarregar o próprio Astro antecipadamente — este será obtido pelo comando do próximo passo. Mas precisa do ambiente onde tudo isto funciona. O Astro descreve assim os primeiros passos — são necessárias três coisas:

Vejamos o que significa cada uma destas coisas na prática:

1. Node.js — um programa sem o qual nem o Astro nem a maioria das ferramentas de vibe-coding funcionam. Descarregue-o de nodejs.org e instale-o como uma aplicação normal. O número da versão indicado na documentação aumenta com o tempo, por isso, antes de começar, visite a página de instalação do Astro e confirme os requisitos. Precisa de uma versão com número par (22, 24); é melhor evitar as versões ímpares (23, 25).
2. VS Code — um editor gratuito da Microsoft. Abra nele a pasta do projeto; o Claude Code também funciona aí e escreverá o código.
3. Terminal — uma janela onde introduz comandos. Não precisa de o instalar à parte: abra-o no menu do VS Code e introduza aí todos os comandos abaixo.

Se já instalou o Claude Code e criou alguma coisa, já tem tudo isto e pode saltar este passo. Caso contrário, tenho um guia separado sobre como instalar o Claude Code.

Como criar um projeto Astro com um único comando?#

É aqui que começa o projeto propriamente dito, e basta um comando. Abra o terminal e introduza:

npm create astro@latest

Será iniciado o assistente de instalação. Eis o que a documentação diz sobre ele:

O assistente guiará o processo e fará algumas perguntas: que nome dar à pasta do projeto, com que modelo começar e se pretende instalar as dependências de imediato. Pode escolher as opções predefinidas para todas as perguntas — um modelo vazio ou minimalista serve para o seu primeiro site. Se respondeu «não» à pergunta sobre a instalação das dependências, instale-as manualmente mais tarde executando o comando npm install dentro da pasta do projeto.

Quando o assistente terminar, indicará que o projeto foi criado e sugerirá o passo seguinte — aceder à pasta do projeto:

cd your-project-name

E é tudo o que precisa para criar o projeto. No interior já existe uma estrutura funcional do site: vários ficheiros e pastas usados para criar a página. Não terá de os editar à mão, mas é útil saber o que está em cada local. Para o Astro, só há uma pasta obrigatória:

Por outras palavras, src/pages é a pasta que contém as páginas do site: a página inicial, «sobre nós» e contactos. Nas proximidades encontram-se normalmente src/components (elementos reutilizáveis, como cabeçalhos e botões), src/layouts (a estrutura comum das páginas) e a pasta public para imagens e ficheiros. Não tem de memorizar a estrutura — basta ter presente que as páginas estão em src/pages e referir isso quando pedir ao Claude: «adiciona uma página de contactos».

Como criar o próprio site através do Claude Code?#

A estrutura inicial está pronta; agora, o site é criado a partir dela, e o Claude Code trata do trabalho. Abra a pasta do projeto no VS Code, inicie o Claude Code e descreva por palavras o que pretende. Ele próprio edita os ficheiros em src/pages e nas pastas próximas — basta dar-lhe tarefas e ver o resultado.

Pela minha experiência, o melhor é trabalhar em pequenos passos. Um único pedido enorme, como «cria-me um site para uma empresa», acaba num conjunto confuso que é difícil de corrigir. Por isso, divida o trabalho em tarefas curtas e claras e apresente-as uma de cada vez:

1. «Cria uma página inicial: um título grande, algumas frases sobre aquilo que faço e um botão com ligação para a página de contactos.»
2. «Adiciona uma página de serviços com uma lista de três secções.»
3. «Adiciona uma página de contactos com um número de telefone e uma ligação para o Telegram.»
4. «Altera o estilo: fundo claro e um tipo de letra grande e legível.»

Verifique cada passo antes de avançar — assim é mais fácil detetar quando alguma coisa está errada e voltar atrás. A razão pela qual as tarefas pequenas são mais fiáveis e a forma de manter a IA no rumo certo fazem parte da engenharia de contexto: quanto mais claras forem a tarefa e a estrutura do projeto, mais previsível será o resultado.

O Astro dá à IA uma estrutura conveniente para este trabalho: o conteúdo das páginas está separado dos estilos, e as páginas são criadas segundo regras comuns. Com esta estrutura, o Claude fica menos vezes confuso e tem menos probabilidade de estragar algo nas proximidades quando edita uma parte. Se o Claude deixar de ver os seus ficheiros ou começar a responder de forma irrelevante, consulte o guia sobre porque é que o Claude Code não consegue ver os ficheiros do projeto.

O Astro é apenas uma das peças do trabalho com IA. Para ajudar o Claude a criar de forma consistente aquilo de que precisa, sem recorrer a suposições plausíveis, a configuração completa do projeto inclui: clone de IA + Segundo Cérebro + Engenharia de Contexto.

Como pré-visualizar o site antes de o publicar?#

Antes de mostrar o site ao mundo, pré-visualize-o no seu próprio computador. Para isso, o Astro tem um servidor de desenvolvimento — mostra o site em tempo real diretamente no seu computador. Inicie-o com um comando no terminal, dentro da pasta do projeto:

npm run dev

O Astro iniciará uma pré-visualização local e apresentará o endereço no terminal. Por predefinição, é localhost:4321. Copie o endereço, abra-o no navegador e verá o site. Por enquanto, só você pode abrir este endereço — ninguém de fora consegue aceder-lhe; é o seu rascunho.

A vantagem é que a pré-visualização é dinâmica: o Claude edita um ficheiro e a página no navegador atualiza-se automaticamente; não precisa de a atualizar manualmente. É rápido — peça algo ao Claude, veja no navegador, faça uma correção, volte a ver, e é nesta fase que aperfeiçoa o site. Quando estiver satisfeito com o resultado, publique-o online.

Como publicar gratuitamente um site Astro online?#

Precisa de colocar o site concluído num local onde outras pessoas o possam abrir através de uma ligação. A forma gratuita mais simples é através do GitHub: primeiro, carregue o código do projeto para um repositório e, depois, ligue um serviço de alojamento que crie e publique o site. Eis a sequência:

1. Crie um repositório no GitHub. Um repositório é um local online para guardar código, onde envia os ficheiros do projeto. O Claude Code pode ajudar com instruções em linguagem natural: peça-lhe «carrega o projeto para um novo repositório GitHub» e ele sugerirá comandos. Se nunca usou o GitHub, tenha à mão instruções para se registar e iniciar sessão.
2. Ligue o alojamento. Aceda a um dos serviços (Netlify, Vercel), inicie sessão através da sua conta GitHub e escolha o repositório. A documentação do Astro descreve este método da seguinte forma: o serviço de alojamento monitoriza o seu repositório, cria o site e publica-o.
3. Verifique as definições de compilação. Normalmente, o serviço de alojamento reconhece o Astro e preenche o que é necessário. Se lhe pedir para introduzir as definições manualmente, o comando de compilação indicado na documentação é astro build (ou npm run build), e o site concluído é colocado na pasta dist.
4. Clique em «Publicar». O serviço criará o site e dar-lhe-á uma ligação como site-name.netlify.app. Qualquer pessoa pode abrir o site nesse endereço.

Eis a formulação exata da documentação sobre como ligar um repositório a um serviço de alojamento:

Depois disso, a publicação passa a ser automática: envie uma nova alteração para o repositório, e o site é recriado e atualizado por si; não precisa de clicar em mais nada.

Há também uma segunda opção gratuita — GitHub Pages, onde o site é publicado diretamente a partir do repositório com as ferramentas do próprio GitHub. O Astro tem uma configuração inicial oficial para isso:

Com esta opção, o site fica acessível num endereço como your-name.github.io/repository-name, e mais tarde pode associar-lhe o seu próprio domínio. Também pode tratar da configuração através do Claude Code: descreva a tarefa por palavras e ele prepara o ficheiro necessário.

Quanto custa criar um site Astro?#

Agora, falemos de dinheiro. O próprio Astro é uma ferramenta gratuita e de código aberto; não tem um preço à parte. Os serviços básicos de alojamento também oferecem opções gratuitas: GitHub Pages e os planos de entrada da Netlify e da Vercel, que costumam ser suficientes para um site Astro leve (os planos gratuitos têm limites de tráfego, mas geralmente chegam para um site de apresentação simples ou uma página de destino).

Na prática, há duas coisas pelas quais poderá pagar, e nem sempre é necessário pagar por ambas. A primeira é o serviço de IA que utiliza para criar o site. A segunda é um domínio próprio em vez de um endereço como name.netlify.app; é opcional e custa pouco por ano. Pode concluir o percurso de criar um site e publicá-lo online pagando apenas pelo Claude.

Que outras perguntas fazem sobre sites Astro e o Claude Code?#

A configuração completa para vibe-coding: clone de IA + Segundo Cérebro + Engenharia de Contexto.

Conheça o Ailoot.