2  Decolando com Astro

No capítulo anterior, você preparou o terreno: criou o repositório no GitHub, inicializou sua estação de trabalho nas nuvens com o GitHub Codespaces e compreendeu a rotina fundamental de versionamento com o Git.

Agora, chegou o momento de instalarmos e darmos vida ao Astro!

A TED System tem como missão “Desenvolver soluções de software personalizadas, seguras e escaláveis que simplifiquem processos, aumentem a produtividade e impulsionem o crescimento dos nossos clientes.” O Astro é uma excelente escolha para esse objetivo. Enquanto muitos frameworks tradicionais enviam megabytes de JavaScript pesado para o navegador do visitante — tornando o carregamento lento —, o Astro adota a filosofia de Zero JavaScript por padrão. Ele gera páginas HTML, processando tudo no momento da construção e entregando o que o usuário precisa ver com ótimo desempenho.

Neste capítulo, você dará os primeiros passos práticos: executará o assistente oficial de criação do Astro, entenderá o propósito de cada pasta e arquivo gerado, inicializará seu primeiro servidor de desenvolvimento na nuvem e registrará tudo no Git.

2.1 Instalando o Astro no GitHub Codespaces

Vamos trabalhar diretamente no terminal integrado do Codespaces. Se o terminal integrado ainda não estiver visível na parte inferior da tela:

• Pressione o atalho de teclado Ctrl + ` (ou Ctrl + ' dependendo do layout do seu teclado);
• Ou clique no ícone de menu principal (as três barrinhas horizontais no canto superior esquerdo), navegue até Terminal e clique em Novo Terminal (New Terminal).

2.1.1 Verificando sua localização com pwd

Antes de executar comandos de instalação, confirme se o terminal está apontado para a raiz do seu projeto executando o comando a seguir (documentação do pwd):

pwd

O terminal deve exibir exatamente:

/workspaces/ted-system-site

2.1.2 Preparando o Diretório e Executando o Instalador

O Astro possui um assistente oficial de linha de comando chamado create-astro, que monta a fundação do projeto.

Antes de executá-lo, precisamos de um pequeno cuidado: o assistente valida o diretório de destino e exige que não existam arquivos estranhos ao controle de versão. Como criamos um README.md temporário no Capítulo 1 para habilitar a inicialização do Codespace, vamos removê-lo agora no terminal, usando o comando rm (remove) (documentação do rm):

rm README.md

Não se preocupe: logo após a instalação da base do Astro, nós recriaremos o README.md oficial com as informações completas da TED System!

2.1.3 Executando o assistente de instalação com opções explícitas

Para que o ambiente seja configurado com previsibilidade e reprodutibilidade — garantindo que qualquer estudante obtenha o mesmo resultado —, utilizaremos o comando com a versão fixada e todas as opções pré-definidas (documentação do npm create):

npm create astro@5.2.4 ./ -- --template minimal --install --no-git --no-ai --yes

DicaO que significa cada parâmetro deste comando?

• npm create astro@5.2.4: Executa o pacote create-astro na versão exata 5.2.4.
• ./: Define o diretório atual como raiz do projeto.
• --template minimal: Seleciona o modelo limpo e enxuto do Astro, com o essencial para construirmos a aplicação do zero.
• --install: Realiza automaticamente a instalação dos pacotes de dependência via NPM.
• --no-git: Preserva o repositório Git já clonado e ativo no Codespaces, evitando conflitos de controle de versão.
• --no-ai: Omite a geração de arquivos de apoio a ferramentas de IA (AGENTS.md e CLAUDE.md), já que o livro não utiliza ferramentas de IA.
• --yes: Aceita as configurações de forma automatizada, sem pausas em perguntas interativas no terminal.

O terminal perguntará se você permite a instalação dos pacotes do assistente (Ok to proceed? (y)). Digite y e pressione a tecla Enter.

A saída do terminal confirmará a criação dos arquivos e a instalação das dependências. Você pode ignorar o aviso final do npm sugerindo uma atualização (New major version of npm available!); atualizar o NPM mudaria o ambiente que testamos para este livro. Veja a saída esperada:

Need to install the following packages:
create-astro@5.2.4
Ok to proceed? (y) y
> npx
> 'create-astro' ./ --template minimal --install --no-git --no-ai --yes
astro   Launch sequence initiated.
      ◼  dir Using ./ as project directory
      ◼  tmpl Using minimal as project template
      ◼  Nice! Git has already been initialized
      ✔  Project initialized!
         ■ Template copied
         ■ Dependencies installed
  next   Liftoff confirmed. Explore your project!
         Run npm run dev to start the dev server. q + ENTER to stop.
         Add frameworks like react or tailwind using astro add.
         Stuck? Join us at https://astro.build/chat
npm notice
npm notice New major version of npm available! 11.19.0 -> 12.1.0
npm notice Changelog: https://github.com/npm/cli/releases/tag/v12.1.0
npm notice To update run: npm install -g npm@12.1.0
npm notice

2.1.4 Fixando a versão exata do Astro

Após a instalação inicial, vamos garantir que o projeto utilize estritamente a versão homologada para este livro, evitando atualizações inesperadas que possam causar incompatibilidades. Execute o comando (documentação do npm install):

npm install astro@7.3.5 --save-exact

A opção --save-exact do NPM grava a versão exata no arquivo de dependências do projeto. A saída do terminal confirmará a atualização (os números de tempo e pacotes podem variar levemente):

up to date, audited 188 packages in 1s

71 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Você pode conferir no arquivo package.json gerado que a dependência agora está registrada exatamente como "astro": "7.3.5", sem o acento circunflexo (^).

Você pode listar o conteúdo do diretório atual utilizando o comando ls com a opção -a (para mostrar arquivos ocultos que começam com ponto):

ls -a

A saída mostrará os arquivos e pastas criados:

.  ..  .git  .gitignore  .vscode  README.md  astro.config.mjs  node_modules  package-lock.json  package.json  public  src  tsconfig.json

2.2 Anatomia do Projeto: Entendendo a Estrutura de Pastas

Antes de explorarmos a estrutura, vamos fazer uma pequena limpeza. O template gerou dois arquivos que não utilizaremos no nosso projeto: a pasta de configurações do editor (.vscode/) e o ícone de página padrão do Astro (public/favicon.ico). O projeto usará suas próprias configurações. O ícone que aparece na aba do navegador (favicon.svg) veio junto com o template e será mantido.

Execute os comandos a seguir para removê-los:

rm -r .vscode
rm public/favicon.ico

O argumento -r no primeiro comando diz ao sistema para remover a pasta e todo o conteúdo dentro dela de forma recursiva.

Agora, abra o Explorador de Arquivos na lateral esquerda do Codespaces. Sua árvore de arquivos terá a seguinte estrutura (note que o editor pode agrupar as pastas src/pages em uma única linha visualmente):

Figura 2.1: Visão da árvore de arquivos inicial no Explorador do Codespaces

Cada um desses arquivos e pastas desempenha um papel fundamental na arquitetura do Astro:

2.2.1 A pasta src/ (Código-Fonte)

A pasta src/ (abreviação de source, ou código-fonte) é a pasta principal do desenvolvedor. Praticamente todo o código que você escrever ao longo deste livro — páginas, componentes reutilizáveis, estilos CSS e layouts — ficará guardado aqui dentro.

Tudo o que está em src/ passa pelo compilador do Astro: seus arquivos são processados, otimizados e transformados em HTML enxuto antes de irem para a internet.

NotaA importância da subpasta src/pages no roteamento do Astro

Dentro de src/, existe uma pasta chamada src/pages/. Ela é o coração do sistema de roteamento baseado em arquivos (file-based routing) do Astro.

Em frameworks tradicionais, muitas vezes é necessário escrever longos arquivos de configuração apenas para associar uma URL (como /sobre ou /contato) a um arquivo de código. No Astro, isso é totalmente automático:

• O arquivo src/pages/index.astro torna-se automaticamente a página inicial do site (/).
• Se no futuro criarmos um arquivo chamado src/pages/sobre.astro, o Astro criará a rota http://meusite.com/sobre.
• Se criarmos uma pasta src/pages/servicos/ com um arquivo consultoria.astro, a URL correspondente será /servicos/consultoria.

A pasta src/pages/ define a estrutura de navegação do site da TED System de maneira simples, intuitiva e sem complicação de código extra.

2.2.2 A pasta public/ (Arquivos Estáticos)

A pasta public/ é reservada para arquivos estáticos que não mudam e que não devem ser processados pelo compilador do Astro.

Exemplos típicos:

• O ícone da aba do navegador (favicon.svg ou favicon.ico);
• Arquivos de configuração de mecanismos de busca (robots.txt);
• Fontes customizadas baixadas em arquivo físico;
• Imagens brutas que você não deseja que o Astro redimensione ou converta.

Qualquer arquivo colocado dentro de public/ é servido exatamente na raiz do site. Por exemplo, o arquivo public/favicon.svg fica acessível publicamente na URL /favicon.svg.

2.2.3 O arquivo astro.config.mjs

Este arquivo em formato JavaScript (.mjs = Module JavaScript) é o painel de controle do Astro. É nele que configuramos integrações e regras gerais de comportamento da ferramenta.

Como começamos com o template mínimo (minimal), o conteúdo do arquivo é simples e direto. O instalador já criou este arquivo, e você não precisa alterá-lo:

astro.config.mjs

// @ts-check
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});

A primeira linha (// @ts-check) habilita a verificação de tipos do TypeScript neste arquivo, ajudando o editor a sugerir configurações corretas enquanto você digita.

2.2.4 O arquivo tsconfig.json

O Astro adota internamente tipagem e padrões estritos para garantir confiabilidade no código. O arquivo tsconfig.json é pré-configurado automaticamente pelo Astro com regras recomendadas, sem exigir que você configure nada manualmente. Mesmo utilizando JavaScript comum, o editor aproveita esse arquivo para oferecer sugestões inteligentes de código e autocompletar.

2.2.5 O arquivo package.json

É a certidão de nascimento do projeto Node.js. Ele lista o nome do projeto, a versão das dependências instaladas e os scripts de automação.

O instalador já criou este arquivo, e você não precisa alterá-lo. Dê uma olhada no conteúdo do package.json:

package.json

{
  "name": "ted-system-site",
  "type": "module",
  "version": "0.0.1",
  "engines": {
    "node": ">=22.12.0"
  },
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "astro": "7.3.5"
  },
  "allowScripts": {
    "esbuild": true
  }
}

O campo "engines" documenta a versão mínima do Node.js exigida pelo projeto (versão 22.12.0 ou superior). O campo "allowScripts" é uma medida de segurança introduzida em versões recentes do NPM para permitir que apenas pacotes expressamente autorizados executem scripts de instalação automaticamente.

O script "dev": "astro dev" é o responsável por disparar o servidor de desenvolvimento que utilizaremos no próximo passo. Já o "build": "astro build" é utilizado para gerar o site final estático que publicaremos na nuvem.

2.3 Restaurando o README.md Institucional da TED System

O instalador do Astro gerou um README.md genérico de boas-vindas. Vamos agora restaurar a identidade oficial da TED System:

1. No Explorador de Arquivos à esquerda, clique sobre README.md para abri-lo.
2. Substitua todo o conteúdo pelo texto oficial da empresa:

README.md

# TED System

> Tecnologia que evolui com o seu negócio.

## Sobre a Empresa
Desenvolver soluções de software personalizadas, seguras e escaláveis que simplifiquem processos, aumentem a produtividade e impulsionem o crescimento dos nossos clientes.

## Localização
- **Endereço:** Rua Coronel Simplício, 250, Sala 12
- **Local:** Centro, Piripiri, PI - CEP 64260-000

## Equipe
- **Wanderson de Vasconcelos** — CEO e Engenheiro de Software
- **Sheldon Cooper** — Especialista Full Stack
- **Amy Farrah Fowler** — Especialista em Bancos de Dados

3. Salve o arquivo pressionando Ctrl + S (ou Cmd + S no Mac).

2.4 Fixando a Versão do Node.js com .node-version

O Astro 7 requer Node.js na versão 22.12.0 ou superior. Para assegurar que a nossa futura plataforma de deploy na nuvem (Cloudflare Pages) utilize a mesma versão que a plataforma na qual testamos o projeto (Node.js 24), vamos criar na raiz do projeto o arquivo .node-version.

No terminal integrado, execute o comando (documentação do echo):

echo "24.21.0" > .node-version

Esse arquivo contém simplesmente a string 24.21.0 (o mesmo valor que você obteria ao verificar a versão do Node.js no Codespaces). Ele instrui de forma automática a Cloudflare a adotar a mesma versão do interpretador para construir o projeto, garantindo compatibilidade. Isso não afeta o Codespaces, que já utiliza nativamente a versão correta da imagem de contêiner.

2.5 Subindo o Servidor de Desenvolvimento no Codespaces

Agora que a estrutura está pronta e as dependências instaladas, vamos ver o Astro em ação!

No terminal do Codespaces, execute o seguinte comando (veja a documentação oficial do comando run no npm):

npm run dev

O terminal iniciará o servidor local do Astro e exibirá mensagens parecidas com estas:

> ted-system-site@0.0.1 dev
> astro dev

▶ Astro collects anonymous usage data.
  This information helps us improve Astro.
  Run "astro telemetry disable" to opt-out.
  https://astro.build/telemetry

17:50:58 [vite] connected.
17:50:58 [types] Generated 0ms
17:50:58 [vite] connected.
astro  v7.3.5 ready in 381 ms
┃ Local    http://localhost:4321/
┃ Network  use --host to expose
17:50:58 watching for file changes...
17:51:14 [200] / 19ms

A primeira mensagem é um aviso sobre a coleta de dados de telemetria anônimos pela equipe do Astro, o que não requer nenhuma ação da nossa parte.

2.5.1 Visualizando o site no navegador do Codespaces

Como você está programando em uma máquina virtual remota na nuvem e não no seu computador físico, o endereço http://localhost:4321 existe dentro do contêiner do Codespaces.

Mas como acessá-lo pelo seu navegador? O GitHub Codespaces resolve isso de forma transparente para você através do redirecionamento de portas (Port Forwarding):

1. No painel inferior do VS Code (ao lado da aba Terminal), clique na aba Portas (Ports).
2. Localize a porta 4321.
3. Passe o mouse sobre a coluna Endereço Encaminhado (Forwarded Address) e clique no ícone do globo com uma seta (Abrir no Navegador ou Open in Browser).

Figura 2.2: Aba Portas no terminal mostrando o endereço encaminhado

(É possível que o editor exiba temporariamente uma notificação pop-up informando que o aplicativo está disponível na porta 4321; você também pode clicar no botão dessa notificação).

Uma nova aba do seu navegador será aberta com a página inicial gerada pelo Astro!

Ao observar a tela da página no navegador, você notará uma barra flutuante na parte inferior central da página. Essa é a Barra de Ferramentas do Astro (Astro Dev Toolbar). Ela é uma ferramenta exclusiva do modo de desenvolvimento (não aparece para os usuários finais do site) e fornece atalhos úteis para inspecionar componentes, auditar acessibilidade e acessar documentações do Astro diretamente pela página.

Figura 2.3: Barra de Ferramentas do Astro visível no navegador

2.5.2 Fazendo sua primeira alteração com recarregamento instantâneo

O Astro vem equipado com o recurso de Hot Module Replacement (HMR). Isso significa que, enquanto o servidor estiver rodando com npm run dev, qualquer arquivo que você salvar no editor atualizará a página no navegador em uma fração de segundo, sem necessidade de recarregar a página manualmente (F5).

Vamos testar isso agora mesmo:

1. No Explorador de Arquivos à esquerda, abra o arquivo src/pages/index.astro.
2. Observe que ele possui uma estrutura HTML simples.
3. Altere o conteúdo e adicione os dados da TED System. Deixe o arquivo com o seguinte código:

src/pages/index.astro

---
// src/pages/index.astro
---

<html lang="pt-BR">
	<head>
		<meta charset="utf-8" />
		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
		<meta name="viewport" content="width=device-width" />
		<title>TED System | Tecnologia que evolui com o seu negócio.</title>
	</head>
	<body>
		<h1>TED System</h1>
		<p>Tecnologia que evolui com o seu negócio.</p>
	</body>
</html>

Neste arquivo, você encontra a estrutura básica de um componente Astro (arquivos com a extensão .astro). Ele possui duas partes: o bloco superior delimitado por --- (chamado de frontmatter, onde colocaremos código JavaScript futuramente) e o bloco inferior com o HTML padrão da página. Você pode ler mais na documentação oficial sobre Componentes Astro.

4. Pressione Ctrl + S (ou Cmd + S) para salvar o arquivo.
5. Volte para a aba do navegador onde o site está aberto: o texto foi atualizado instantaneamente no navegador!

2.6 Construindo o Projeto para Produção

O comando npm run dev é útil enquanto estamos programando. Mas como o Astro prepara esses arquivos para serem publicados de forma eficiente na internet?

Para ver isso na prática, primeiro precisamos parar o servidor de desenvolvimento. Volte à aba do terminal e pressione as teclas Ctrl + C. Essa é a forma universal de interromper qualquer programa em execução no terminal (atenção: no Mac também é Ctrl + C, e não Cmd + C, que serve para copiar texto). Opcionalmente, como informado na mensagem final do instalador, o Astro também permite parar o servidor pressionando a tecla q e, em seguida, a tecla Enter.

Agora, execute o comando de construção (build) (documentação do npm run script):

npm run build

A saída mostrará o Astro compilando os arquivos:

> ted-system-site@0.0.1 build
> astro build

18:42:32 [vite] Re-optimizing dependencies because vite config has changed
18:42:33 [types] Generated 180ms
18:42:33 [build] output: "static"
18:42:33 [build] mode: "static"
18:42:33 [build] directory: /workspaces/ted-system-site/dist/
18:42:33 [build] Collecting build info...
18:42:33 [build] ✓ Completed in 216ms.
18:42:33 [build] Building static entrypoints...
18:42:33 [vite] ✓ built in 276ms
18:42:33 [vite] ✓ built in 18ms
18:42:33 [build] Rearranging server assets...

 generating static routes 
18:42:33   ├─ /index.html (+14ms) 
18:42:33 ✓ Completed in 31ms.

18:42:33 [build] ✓ Completed in 365ms.
18:42:33 [build] 1 page(s) built in 583ms
18:42:33 [build] Complete!

(Os horários e os tempos de carregamento variam a cada execução).

O Astro pegou o arquivo src/pages/index.astro, processou o código e gerou um arquivo estático leve e rápido. Todos os arquivos finais prontos para a internet foram colocados em uma nova pasta chamada dist/ (de distribution). É o conteúdo dessa pasta que enviaremos para a plataforma Cloudflare Pages no final do livro.

No entanto, se você verificar o status do controle de versão mais tarde, perceberá que a pasta dist/ não será enviada para o GitHub. Isso acontece porque o arquivo oculto .gitignore já está configurado para ignorá-la. Apenas o código-fonte importa no GitHub; os arquivos de distribuição são gerados sob demanda.

2.7 O Ciclo do Git

Com a base do site funcionando, precisamos registrar as alterações no histórico do Git e sincronizar com o GitHub.

No terminal, execute o ciclo dos três passos que aprendemos no Capítulo 1:

2.7.1 Verificando as modificações com git status

Execute o comando (documentação do git status):

git status

O Git exibirá a lista de todos os novos arquivos criados pelo instalador do Astro (astro.config.mjs, package.json, package-lock.json, pasta src/, etc.).

DicaPor que a pasta node_modules/ e a dist/ não aparecem no git status?

O assistente do Astro criou automaticamente um arquivo chamado .gitignore. Dentro dele estão especificadas as linhas node_modules/ e dist/. Isso instrui o Git a nunca enviar os milhares de arquivos de dependências ou os artefatos compilados para o GitHub, mantendo o repositório leve e focado apenas no seu código-fonte.

2.7.2 Preparando os arquivos com git add .

Adicione todos os novos arquivos à área de preparação (staging) com o comando (documentação do git add):

git add .

2.7.3 Criando o ponto de restauração com git commit

No Capítulo 1, usamos uma mensagem simples de propósito. A partir deste capítulo, adotaremos o padrão internacional Conventional Commits para as nossas mensagens de commit. Esse padrão exige que o texto seja iniciado por um prefixo que indique o tipo da alteração:

• feat: para uma nova funcionalidade (feature);
• fix: para uma correção de erro;
• docs: para atualizações na documentação.

O texto após o prefixo deve ser escrito em português correto. Registre as modificações com a mensagem adequada executando o comando (documentação do git commit):

git commit -m "feat: cria o projeto Astro da TED System"

2.7.4 Enviando as alterações para a nuvem com git push

Envie o commit registrado localmente para o repositório no GitHub executando o comando a seguir (documentação do git push):

git push

Pronto! Acesse o seu repositório no GitHub pelo navegador e confirme: todos os arquivos do projeto Astro da TED System estão salvos na nuvem.

2.8 Resumo e Próximos Passos

Você concluiu uma das etapas mais importantes da formação: a criação da espinha dorsal do projeto.

Neste capítulo, você aprendeu a:

• Utilizar o instalador oficial npm create astro com versão fixa e opções explícitas diretamente no terminal do Codespaces;
• Configurar as opções recomendadas para um início automatizado e enxuto;
• Fixar a versão recomendada do Node.js criando o arquivo .node-version;
• Compreender o papel de cada diretório e arquivo gerado (src/, public/, astro.config.mjs, tsconfig.json e package.json);
• Reconhecer o sistema de roteamento baseado em arquivos da pasta src/pages/;
• Iniciar o servidor de desenvolvimento com npm run dev e acessar a aplicação na nuvem através do gerenciador de portas do Codespaces;
• Compilar o projeto final otimizado para produção utilizando o comando npm run build;
• Versionar todo o código inicial com o ciclo git add, git commit e git push utilizando o padrão Conventional Commits.

No próximo capítulo, vamos estudar o sistema de Páginas e Roteamento. Criaremos novas rotas para a TED System, exploraremos a sintaxe dos arquivos .astro e construiremos a navegação entre a página inicial e a página institucional da empresa. Nos vemos lá!