Introducción
Durante años, codificar un sitio web a mano fue el estándar de oro para desarrolladores que querían control total sobre cada línea de HTML, CSS y JavaScript. Ofrecía una flexibilidad inigualable y un conocimiento profundo del código. Pero a medida que los sitios web crecen, más páginas, más contenido, más complejidad, ese enfoque artesanal puede convertirse en una pesadilla de mantenimiento. Te encuentras copiando y pegando barras de navegación, actualizando pies de página en docenas de archivos y optimizando manualmente los recursos para el rendimiento.
Esa es exactamente la situación en la que se encontraba el autor del artículo de How-To Geek. Su sitio web, rediseñado por última vez alrededor de 2018, había pasado de admitir seis o siete libros a muchos más. El parcheo y la adición manual se habían vuelto insostenibles. ¿La solución? Reconstruir todo el sitio con Astro, un generador de sitios estáticos moderno que promete velocidad, simplicidad y una mejor experiencia para el desarrollador.
En esta publicación, analizaremos ese proceso de migración, exploraremos las decisiones técnicas detrás de él y te mostraremos cómo puedes aplicar los mismos principios a tus propios proyectos. Ya sea que mantengas un blog personal, un portafolio o un sitio de documentación, las lecciones aquí son directamente aplicables.
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.
La Experiencia del Desarrollador: Por Qué Astro Gana
Más allá del rendimiento, la experiencia del desarrollador al trabajar con Astro es una razón principal para migrar. Aquí hay algunos aspectos que el autor de How-To Geek probablemente apreció.
Reemplazo de Módulo en Caliente (HMR)
Cuando estás desarrollando localmente, el servidor de desarrollo de Astro proporciona retroalimentación instantánea. Cambia un componente y el navegador se actualiza sin recargar la página completa. Esto es un gran impulso en productividad en comparación con actualizar manualmente el navegador después de cada edición.
Ecosistema de Integraciones
Astro tiene un ecosistema creciente de integraciones para herramientas populares:
- Tailwind CSS: Para estilos basados en utilidades.
- React, Vue, Svelte: Usa componentes de tu framework favorito dentro de Astro.
- MDX: Inserta componentes de React directamente en Markdown.
- Optimización de imágenes: Redimensionamiento automático y conversión de formato.
- Feed RSS: Genera feeds RSS a partir de tus colecciones de contenido.
Esto significa que no estás atado a un solo framework. Puedes usar la mejor herramienta para cada trabajo.
Soporte para TypeScript
Astro tiene soporte de primera clase para TypeScript. Puedes definir interfaces de props para tus componentes, lo que detecta errores en tiempo de compilación en lugar de tiempo de ejecución.
---
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>
Esto detecta errores de tipo temprano y hace que tu código sea más mantenible.
Errores Comunes y Cómo Evitarlos
Migrar de un sitio codificado a mano a Astro es generalmente fluido, pero hay algunos errores comunes a tener en cuenta.
1. Sobreingeniería del Árbol de Componentes
Es tentador crear un componente para todo, incluso un solo párrafo. Pero eso puede llevar a una complejidad innecesaria. Comienza con los elementos más repetitivos (diseño, navegación, tarjetas) y solo crea componentes cuando veas un patrón repetido tres o más veces.
2. Ignorar el Proceso de Compilación
Astro genera un sitio estático, pero aún necesitas configurar el proceso de compilación. Asegúrate de que tu astro.config.mjs incluya la URL site correcta para el mapa del sitio, y que la configuración de optimización de imágenes coincida con tus necesidades.
3. No Usar Colecciones de Contenido para Datos Estructurados
Si tienes una lista de elementos (libros, publicaciones de blog, piezas de portafolio), usa Colecciones de Contenido. Proporcionan seguridad de tipos, paginación automática y filtrado sencillo. Listar elementos manualmente en un componente es un paso atrás.
4. Olvidar las Páginas 404
Los sitios codificados a mano a menudo tienen una página 404 personalizada. En Astro, creas un archivo 404.astro en src/pages/. Se servirá automáticamente para cualquier ruta que no 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 del Mundo Real: Lo que Logró el Autor
El artículo de How-To Geek ofrece una mirada sincera al proceso de migración. El autor no solo reconstruyó el sitio, sino que también mejoró la estructura del contenido, agregó nuevas funciones y optimizó el rendimiento.
Conclusión: ¿Es Astro Adecuado para Tu Sitio Codificado a Mano?
Si mantienes un sitio web codificado a mano que ha crecido más allá de unas pocas páginas, migrar a Astro es probablemente una decisión inteligente. Los beneficios son claros:
- Desarrollo más rápido: Los componentes reutilizables y el contenido en Markdown reducen el trabajo repetitivo.
- Mejor rendimiento: Cero JavaScript por defecto lleva a páginas ultrarrápidas.
- Mejor SEO: Los mapas del sitio automáticos, los datos estructurados y las imágenes optimizadas mejoran las clasificaciones de búsqueda.
- Mantenimiento más fácil: Actualiza un componente una vez y cambia en todas partes.
El proceso de migración en sí mismo es sencillo. Comienza configurando un nuevo proyecto de Astro, extrae tu diseño en un componente, luego convierte tus páginas a archivos Markdown o Astro. Usa Colecciones de Contenido para datos estructurados y aprovecha el ecosistema de integraciones para imágenes, SEO y más.
Astro no es solo una herramienta, es una filosofía. Respeta la artesanía de los sitios codificados a mano mientras proporciona la automatización y escalabilidad que exige el desarrollo web moderno. Si estás listo para dejar atrás el ciclo de copiar y pegar, prueba Astro.
