Introdução
Por anos, codificar um site manualmente foi o padrão ouro para desenvolvedores que desejavam controle total sobre cada linha de HTML, CSS e JavaScript. Isso oferecia flexibilidade incomparável e um profundo entendimento da base de código. Mas, à medida que os sites crescem — mais páginas, mais conteúdo, mais complexidade — essa abordagem artesanal pode se tornar um pesadelo de manutenção. Você se vê copiando e colando barras de navegação, atualizando rodapés em dezenas de arquivos e otimizando manualmente ativos para desempenho.
Foi exatamente essa situação em que o autor do artigo do How-To Geek se encontrou. O site dele, cujo último redesign foi por volta de 2018, havia crescido de suportar seis ou sete livros para muitos mais. A correção e adição manuais haviam se tornado insustentáveis. A solução? Reconstruir todo o site com Astro, um gerador moderno de sites estáticos que promete velocidade, simplicidade e uma melhor experiência para o desenvolvedor.
Neste post, dissecaremos essa jornada de migração, exploraremos as decisões técnicas por trás dela e mostraremos como você pode aplicar os mesmos princípios aos seus próprios projetos. Seja você mantendo um blog pessoal, um portfólio ou um site de documentação, as lições aqui são diretamente aplicáveis.
Enter Astro: The Static Site Generator That Respects Your Code
Astro is a relatively new static site generator that has quickly gained popularity among frontend developers. Its core philosophy is simple: ship zero JavaScript by default, and only load client-side scripts when absolutely necessary. This approach leads to incredibly fast page loads and a smaller carbon footprint.
But what makes Astro particularly appealing for rebuilding a hand-coded website is its component-based architecture. You can create reusable components for headers, footers, cards, and layouts, then compose them into pages. This eliminates the repetitive boilerplate that plagues hand-coded sites.
The Migration Process: Step by Step
Let's walk through the actual steps the author took to rebuild their site with Astro. We'll focus on the technical decisions and code examples that made the transition successful.
Step 1: Setting Up the Astro Project
First, you need to initialize a new Astro project. The official CLI makes this straightforward:
npm create astro@latest my-new-site
During setup, you'll be prompted to choose a template. For a content-heavy site, the "Blog" template is a great starting point. It includes Markdown support, RSS feed generation, and a basic layout.
Once the project is created, you can start customizing the structure. The key folders are:
src/pages/, Each file here becomes a route.src/layouts/, Reusable layout components.src/components/, Smaller UI components.public/, Static assets like images and fonts.
Step 2: Extracting the Layout
In a hand-coded site, every page likely contains the same <header>, <nav>, and <footer> markup. With Astro, you create a single layout component that wraps your page content.
---
// src/layouts/BaseLayout.astro
export interface Props {
title: string;
description?: string;
}
const { title, description } = Astro.props;
---
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>{title}</title>
{description && <meta name="description" content={description} />}
<link rel="stylesheet" href="/styles/global.css" />
</head>
<body>
<header>
<nav>
<a href="/">Home</a>
<a href="/blog">Blog</a>
<a href="/about">About</a>
</nav>
</header>
<main>
<slot /> <!-- Page content goes here -->
</main>
<footer>
<p>© 2025 My Site</p>
</footer>
</body>
</html>
Now every page can use this layout with just a few lines:
---
import BaseLayout from '../layouts/BaseLayout.astro';
---
<BaseLayout title="About Me" description="Learn more about the author.">
<h1>About Me</h1>
<p>I'm a frontend developer who loves Astro.</p>
</BaseLayout>
This single change eliminates hundreds of lines of duplicated HTML across the site.
Step 4: Reusable Components for UI Elements
Beyond layouts, Astro components let you encapsulate any UI pattern. For example, a book card component that displays a cover image, title, and description can be reused across multiple pages.
---
// src/components/BookCard.astro
export interface Props {
title: string;
cover: string;
description: string;
url: string;
}
const { title, cover, description, url } = Astro.props;
---
<article class="book-card">
<img src={cover} alt={title} loading="lazy" />
<h3>{title}</h3>
<p>{description}</p>
<a href={url}>Learn More</a>
</article>
<style>
.book-card {
border: 1px solid #e0e0e0;
border-radius: 8px;
padding: 1rem;
max-width: 300px;
}
.book-card img {
width: 100%;
height: auto;
border-radius: 4px;
}
</style>
Now you can use this component anywhere:
<BookCard
title="Astro for Beginners"
cover="/images/astro-book.jpg"
description="A comprehensive guide to building fast websites with Astro."
url="/books/astro-for-beginners"
/>
This component-based approach not only saves time but also ensures visual consistency across the site.
Performance Gains: What the Numbers Say
One of the most compelling reasons to migrate to Astro is performance. By shipping zero JavaScript by default, Astro pages load incredibly fast. Let's look at some typical improvements.
SEO and Accessibility Improvements
Rebuilding with Astro also opens the door to better SEO and accessibility practices. Here are some specific improvements you can implement.
Semantic HTML and Structured Data
Astro encourages writing semantic HTML because you're composing components rather than copying and pasting. You can easily add structured data (JSON-LD) to your pages for better search engine understanding.
---
// src/components/SEO.astro
const { title, description, url, image } = Astro.props;
---
"@context": "https://schema.org",
"@type": "WebPage",
"name": title,
"description": description,
"url": url,
"image": image,
})} />
Then include this component in your layout:
<SEO title={title} description={description} url={Astro.url} image="/og-image.jpg" />
Automatic Sitemap Generation
Astro has an official sitemap integration that generates a sitemap.xml file at build time. This is crucial for SEO because it helps search engines discover all your pages.
npm install @astrojs/sitemap
Then add it to your astro.config.mjs:
import { defineConfig } from 'astro/config';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
site: 'https://example.com',
integrations: [sitemap()],
});
That's it. Every page in your src/pages/ directory will be included in the sitemap automatically.
A Experiência do Desenvolvedor: Por que o Astro Vence
Além do desempenho, a experiência do desenvolvedor ao trabalhar com Astro é um motivo importante para migrar. Aqui estão alguns aspectos que o autor do How-To Geek provavelmente apreciou.
Substituição de Módulo a Quente (HMR)
Quando você está desenvolvendo localmente, o servidor de desenvolvimento do Astro fornece feedback instantâneo. Altere um componente e o navegador atualiza sem recarregar a página inteira. Isso é um enorme ganho de produtividade em comparação com atualizar manualmente o navegador após cada edição.
Ecossistema de Integrações
O Astro possui um ecossistema crescente de integrações para ferramentas populares:
- Tailwind CSS: Para estilização utilitária.
- React, Vue, Svelte: Use componentes do seu framework favorito dentro do Astro.
- MDX: Incorpore componentes React diretamente no Markdown.
- Otimização de imagens: Redimensionamento automático e conversão de formato.
- Feed RSS: Gere feeds RSS a partir de suas coleções de conteúdo.
Isso significa que você não fica preso a um único framework. Você pode usar a melhor ferramenta para cada tarefa.
Suporte a TypeScript
O Astro tem suporte de primeira classe para TypeScript. Você pode definir interfaces de props para seus componentes, o que captura erros em tempo de compilação em vez de tempo de execução.
---
interface Props {
title: string;
date: Date;
excerpt: string;
tags: string[];
}
const { title, date, excerpt, tags } = Astro.props;
---
<article>
<h2>{title}</h2>
<time datetime={date.toISOString()}>{date.toLocaleDateString()}</time>
<p>{excerpt}</p>
<ul>
{tags.map(tag => <li>{tag}</li>)}
</ul>
</article>
Isso captura erros de tipo precocemente e torna seu código mais sustentável.
Armadilhas Comuns e Como Evitá-las
Migrar de um site codificado manualmente para o Astro é geralmente suave, mas existem algumas armadilhas comuns a serem observadas.
1. Superengenharia da Árvore de Componentes
É tentador criar um componente para tudo, até mesmo para um único parágrafo. Mas isso pode levar a complexidade desnecessária. Comece com os elementos mais repetitivos (layout, navegação, cards) e só crie componentes quando perceber um padrão se repetindo três ou mais vezes.
2. Ignorar o Processo de Build
O Astro gera um site estático, mas você ainda precisa configurar o processo de build. Certifique-se de que seu astro.config.mjs inclua a URL correta do site para o sitemap, e que suas configurações de otimização de imagem atendam às suas necessidades.
3. Não Usar Content Collections para Dados Estruturados
Se você tem uma lista de itens (livros, posts de blog, peças de portfólio), use Content Collections. Elas fornecem segurança de tipos, paginação automática e filtragem fácil. Listar itens manualmente em um componente é um passo para trás.
4. Esquecer da Página 404
Sites codificados manualmente geralmente têm uma página 404 personalizada. No Astro, você cria um arquivo 404.astro em src/pages/. Ele será servido automaticamente para qualquer rota que não exista.
---
import BaseLayout from '../layouts/BaseLayout.astro';
---
<BaseLayout title="Page Not Found">
<h1>404</h1>
<p>Sorry, the page you're looking for doesn't exist.</p>
<a href="/">Go back home</a>
</BaseLayout>
Resultados do Mundo Real: O que o Autor Alcançou
O artigo do How-To Geek oferece uma visão sincera do processo de migração. O autor não apenas reconstruiu o site, mas também melhorou a estrutura de conteúdo, adicionou novos recursos e otimizou o desempenho.
Conclusão: O Astro é Certo para o Seu Site Codificado Manualmente?
Se você está mantendo um site codificado manualmente que cresceu além de algumas páginas, migrar para o Astro é provavelmente uma jogada inteligente. Os benefícios são claros:
- Desenvolvimento mais rápido: Componentes reutilizáveis e conteúdo em Markdown reduzem o trabalho repetitivo.
- Melhor desempenho: Zero JavaScript por padrão leva a páginas extremamente rápidas.
- SEO aprimorado: Sitemaps automáticos, dados estruturados e imagens otimizadas melhoram as classificações em buscas.
- Manutenção mais fácil: Atualize um componente uma vez, e ele muda em todos os lugares.
O processo de migração em si é direto. Comece configurando um novo projeto Astro, extraia seu layout para um componente, depois converta suas páginas para Markdown ou arquivos Astro. Use Content Collections para dados estruturados e aproveite o ecossistema de integrações para imagens, SEO e muito mais.
O Astro não é apenas uma ferramenta, é uma filosofia. Ele respeita o artesanato dos sites codificados manualmente enquanto fornece a automação e escalabilidade que o desenvolvimento web moderno exige. Se você está pronto para deixar o ciclo de copiar e colar para trás, experimente o Astro.
