Durante la última década, construir para la web se volvió increíblemente complejo. Los frameworks de JavaScript (React, Vue, Angular) trajeron soluciones geniales para Single Page Applications (SPAs) complejas, pero a un costo muy alto para el usuario final: megabytes de JavaScript innecesarios que ralentizan los dispositivos móviles y complican el SEO.

Astro llegó para redefinir estas reglas bajo una filosofía radicalmente sencilla: genera HTML estático en el servidor por defecto y no envíes JavaScript al cliente a menos que sea estrictamente necesario.

En esta guía te enseñaré cómo poner en marcha un proyecto de Astro desde cero y te daré algunos consejos de configuración profesional.

1. Puesta en Marcha Desde Cero

Para iniciar tu nuevo proyecto, abre tu terminal y ejecuta el asistente oficial de inicialización:

# Crear un nuevo proyecto interactivo
npm create astro@latest

El asistente te hará un par de preguntas clave:

  1. Directorio del proyecto: Escribe el nombre de tu carpeta (ej. mi-sitio-astro).
  2. Template: Selecciona “Use blog starter kit” si quieres algo ya estructurado, o “Empty” si deseas construir desde cero.
  3. Instalar dependencias: Elige Yes (es muy recomendable que lo haga de una vez).
  4. TypeScript: Elige Yes (te ayudará a evitar errores tipográficos en tus props y configuraciones).

Una vez completado, entra al directorio y levanta el servidor de desarrollo:

cd mi-sitio-astro
npm run dev

Tu servidor local estará activo en http://localhost:4321.

2. Configuración Esencial del Proyecto

El archivo principal de configuración es astro.config.mjs. En este archivo importarás cualquier integración que necesites (como React, Tailwind, Sitemap, etc.):

// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
import react from '@astrojs/react';

export default defineConfig({
  site: 'https://hadercode.dev', // Necesario para generar sitemaps y URLs canónicas correctas
  integrations: [
    tailwind(), // Añade soporte para Tailwind CSS
    react()     // Añade soporte para componentes React
  ],
});

Estructura de Carpetas Recomendada:

  • src/layouts/: Plantillas HTML generales (cabecera, pie de página, metaetiquetas SEO).
  • src/components/: Componentes UI reutilizables (botones, tarjetas, menús).
  • src/pages/: Enrutamiento automático basado en archivos (ej. src/pages/index.astro mapea a /).
  • src/content/: Directorio seguro para colecciones de datos markdown (content.config.ts).
  • public/: Archivos estáticos públicos directos (imágenes, robots.txt, favicon).

3. Anatomía de un Componente Astro (.astro)

Los componentes de Astro son súper limpios y se dividen en dos partes principales usando delimitadores de código (---), conocido como la valla (code fence):

---
// 1. Script del Componente (se ejecuta solo en el Servidor en tiempo de compilación)
import Button from '../components/Button.astro';

interface Props {
  title: string;
  subtitle?: string;
}

const { title, subtitle = "Valor por defecto" } = Astro.props;
---

<!-- 2. Plantilla HTML (se renderiza y se envía al cliente como HTML puro) -->
<div class="card">
  <h2>{title}</h2>
  {subtitle && <p>{subtitle}</p>}
  <Button label="Hacer clic" />
</div>

<style>
  /* 3. Estilos Locales (Automáticamente Scoped por defecto) */
  .card {
    border: 1px solid rgba(255, 255, 255, 0.05);
    padding: 1.5rem;
    border-radius: 8px;
  }
  h2 {
    color: var(--accent-primary);
  }
</style>

4. El Secreto del Rendimiento: Arquitectura de Islas

Si importas un componente interactivo de React en tu página, Astro lo renderizará como HTML estático en el servidor por defecto (0KB de JavaScript en el cliente). Si deseas añadirle interactividad en el navegador, debes hidratar el componente usando una directiva de cliente:

---
import InteractiveCounter from '../components/InteractiveCounter.jsx';
---

<!-- Cero Javascript, renderizado puramente estático -->
<InteractiveCounter />

<!-- Carga JavaScript inmediatamente al cargar la página -->
<InteractiveCounter client:load />

<!-- Carga JavaScript solo cuando el componente sea visible en el scroll -->
<InteractiveCounter client:visible />

<!-- Hidrata únicamente en móvil/pantallas pequeñas -->
<InteractiveCounter client:media="(max-width: 50em)" />

<!-- No se renderiza en servidor, se ejecuta solo en cliente -->
<InteractiveCounter client:only="react" />

5. Extensiones y Herramientas Recomendadas para tu Editor

Para programar con la mejor comodidad técnica en Visual Studio Code, asegúrate de instalar:

  1. Astro (VS Code Extension): Aporta resaltado de sintaxis, autocompletado avanzado y diagnóstico de tipos para archivos .astro.
  2. Prettier - Code Formatter: Formatea automáticamente tus archivos Astro al guardar, alineando HTML, JS y CSS.
  3. Tailwind CSS IntelliSense: Si utilizas Tailwind, esta extensión te brindará autocompletado en tus clases de forma interactiva.
  4. MDX: Si escribes posts interactivos de blog utilizando sintaxis Markdown con componentes enriquecidos.