Estrutura de Pastas Essenciais do Projeto

1. Hook (A Trava Mental)

• Aprendiz: "Mestre, eu vejo várias pastas: src, public, node_modules... parece complexo. Se eu pedir para a IA criar uma nova página, onde exatamente ela deve colocar o arquivo? E se for um elemento reutilizável, como um botão?"

2. Deep Dive (A Solução)

• Mestre: "Excelente pergunta. A estrutura de pastas do Astro não é aleatória; é uma planta baixa lógica e organizada. Pense nela como uma casa bem planejada. Cada pasta tem um propósito claro, e conhecê-los transforma seus prompts para a IA de pedidos vagos em ordens de construção precisas."

Vamos explorar os quatro "cômodos" principais que você precisa dominar.

Para ter uma visão geral e oficial, a documentação do Astro é seu mapa.

Agora, vamos analisar cada pasta com nossas analogias.

A. public/ - A Garagem

• Analogia: Pense na pasta public como a garagem ou o depósito da sua casa. É onde você guarda coisas que não precisam ser construídas ou processadas, apenas movidas para o local final.
• Função: Arquivos aqui são copiados para o site final sem modificação. É o lugar ideal para:
  • Imagens que você não quer que o Astro otimize (logo.svg, favicon.ico).
  • Fontes personalizadas (minha-fonte.woff2).
  • Arquivos especiais como robots.txt ou PDFs para download.
• Em resumo: O que entra em public/ sai exatamente igual no site publicado.

B. src/ - A Oficina

• Analogia: A pasta src (de "source" ou fonte) é a sua oficina de trabalho. É aqui que toda a mágica acontece. O Astro pega os materiais brutos desta pasta (seu código) e os constrói, otimiza e monta para criar o site final.
• Função: Contém todo o seu código-fonte que será processado pelo Astro. Dentro dela, temos três áreas de trabalho cruciais.

C. src/pages - Os Quartos (As Páginas)

• Analogia: Cada arquivo dentro de src/pages é um cômodo da sua casa. O nome do arquivo vira o endereço do cômodo.
• Função: O Astro usa um sistema de roteamento baseado em arquivos.
  • src/pages/index.astro → se torna a página principal do seu site (meusite.com/).
  • src/pages/sobre.astro → se torna a página meusite.com/sobre.
  • src/pages/contato.astro → se torna a página meusite.com/contato.
• Em resumo: Quer criar uma nova página? Basta criar um novo arquivo .astro aqui. É a pasta mais importante e a única que é estritamente obrigatória.

D. src/layouts - A Estrutura (Paredes e Teto)

• Analogia: Usando a analogia do nosso curso, esta é a "Caixa de Pizza". É a estrutura que se repete em várias páginas: o cabeçalho com o logo, o menu de navegação e o rodapé. A página em si é o "recheio" que muda.
• Função: Layouts são componentes especiais que definem a estrutura de uma ou mais páginas. Eles contêm um marcador especial <slot />, que é onde o conteúdo específico de cada página será injetado. Isso evita que você copie e cole o mesmo cabeçalho e rodapé em todos os arquivos.
• Em resumo: Defina o esqueleto da sua página uma vez, reutilize em todo lugar.

E. src/components - A Mobília (Os Blocos de Lego)

• Analogia: Se as páginas são os cômodos, os componentes são a mobília e a decoração que você pode usar em qualquer um deles. Um botão, um card de produto, um formulário de contato. Você constrói a "cadeira" (Button.astro) uma vez e pode colocá-la na sala (index.astro) ou no quarto (sobre.astro).
• Função: São blocos de construção de interface, reutilizáveis e independentes. A essência do Astro é construir sites combinando esses pequenos componentes.
• Em resumo: Tudo que você pretende reutilizar em mais de um lugar deve ser um componente.

3. O Fazer (Explorando na Prática)

Para ver essa estrutura em ação, nada melhor do que um vídeo que percorre essas pastas e explica sua função.

Visualmente, a estrutura no seu editor de código se parecerá com isto:

4. Checkpoint (Dica de IA)

• Mestre: "Perfeito. Agora você não está mais olhando para um amontoado de arquivos. Você está vendo a planta baixa de um arquiteto. Este conhecimento é o seu superpoder para o Context Engineering."

Ao dar instruções para uma IA, você agora pode ser extremamente específico, o que aumenta drasticamente a qualidade do resultado.

• Prompt Genérico (Ruim): "Crie uma página sobre mim."
• Prompt com Contexto (Ótimo): "Atue como um desenvolvedor Astro. Crie uma nova página em src/pages/sobre.astro. Esta página deve usar o layout definido em src/layouts/BaseLayout.astro. Dentro da página, adicione um componente ProfileCard.astro que você criará em src/components/. O ProfileCard deve mostrar uma imagem profile.jpg, que deve ser colocada na pasta public/images/."

Percebe a diferença? O segundo prompt não deixa espaço para ambiguidade. Você está fornecendo o contexto estrutural para a IA trabalhar, garantindo que o código gerado se encaixe perfeitamente no seu projeto.

Conclusão

Nesta lição, você mapeou o território do seu projeto Astro. Você agora entende a lógica por trás da estrutura de pastas.

• Key Takeaways:

  • public/: Para arquivos estáticos, sem processamento (a garagem).
  • src/pages/: Cria as páginas e URLs do seu site (os cômodos).
  • src/layouts/: Define a estrutura reutilizável das páginas (as paredes e o teto).
  • src/components/: Contém os blocos de construção reutilizáveis da sua UI (a mobília).

• Próximo Passo: Conhecemos a planta baixa e a função de cada cômodo. Na próxima lição, vamos pegar uma dessas peças de "Lego" (.astro) e olhar para dentro dela com uma lupa. Vamos dissecar sua anatomia e entender as duas partes que a compõem: a "mente" (o código JavaScript no frontmatter) e o "corpo" (o template HTML).