Astro

Panorama general

Frontend y Backend framework híbrido orientado a contenido.
Enfoque principal en SSG (Static Site Generation), optimizado para sitios rápidos basados en contenido.
Soporte completo para SSR (Server-Side Rendering) cuando el proyecto requiere dinámicas del lado servidor.
Integración fluida con ecosistemas como react, vuejs, Svelte, Solid y otros.
Documentación oficial: Astro

Fundamentos

Arquitectura basada en Islands Architecture, donde solo partes interactivas del sitio se hidratan en cliente.
“Island components” ejecutados en el servidor por defecto, minimizando el JS enviado al navegador.
Fuerte soporte para Markdown, MDX y contenido estático como base de proyectos orientados a documentación o blogs.
Compatibilidad con Layouts, Collections, y la API unificada de contenido Content Collections.
Rutas basadas en archivos (/src/pages), compatible con APIs serverless mediante .js/.ts en el mismo sistema de rutas.

Características clave

Render por defecto en servidor, enviando HTML pre-generado ultra-eficiente.
Zero-JS por defecto: “bring your own framework” sin cargar nada al cliente a menos que se especifique.
Hibridación inteligente usando directivas (client:load, client:idle, client:visible, etc.).
Integración con herramientas modernas: Vite, TypeScript, Tailwind, y adaptadores para múltiples plataformas.

Island Components

Componentes interactivos aislados.
Se procesan en servidor y envían al cliente solo cuando es estrictamente necesario.
Permiten mezclar múltiples frameworks en un mismo proyecto sin coste adicional en arquitectura.

Markdown y Contenido

Soporta .md y .mdx, convirtiendo cada archivo en una ruta si se ubica en src/pages.
“Content Collections” permiten tipado, validación y organización de contenido estructurado.
Soporte para frontmatter YAML con tipado automático en TypeScript.
astro:content aporta utilidades para cargar, validar y transformar contenido antes del render.

Integración con Frameworks

Puedes usar componentes de:
- react
- vuejs
- Svelte
- solid.js
- Preact
Cada framework puede ser hidratado de forma independiente usando directivas cliente.
Ideal para migraciones parciales o proyectos multicapa.

SSR (Server-Side Rendering)

Modo opcional para apps con:
- Autenticación
- Personalización de contenido
- Integración con bases de datos
Adaptadores disponibles para:
- Node
- Deno
- Cloudflare
- Netlify
- Vercel

Bloques de código

Ejemplo básico de página Astro

---
// Frontmatter en Astro: JS/TS ejecutado en el servidor
const title = "Hola desde Astro";
---
<html>
	<head>
		<title>{title}</title>
	</head>
	<body>
		<h1>{title}</h1>
		<p>Esta es una página generada con Astro.</p>
	</body>
</html>

Uso de un componente React como “island”

---
import Counter from "../components/Counter.jsx";
---
<div>
	<h2>Contador interactivo</h2>
	<Counter client:idle />
</div>

Ejemplo simple de Markdown convertido en página

---
title: "Mi página en Markdown"
description: "Astro convierte Markdown en HTML automáticamente"
---

# Hola desde Markdown
Contenido estático, rápido y limpio.

Ejemplo de Collection

import { defineCollection, z } from "astro:content";

export const collections = {
	blog: defineCollection({
		schema: z.object({
			title: z.string(),
			date: z.string(),
			tags: z.array(z.string()).optional()
		})
	})
};

Astro — Expansión de conceptos faltantes

¿Qué conceptos quedaban por cubrir?

Aún quedaban áreas relevantes que no se habían cubierto y que completan la visión global de Astro sin repetir lo anterior:

Sistema de rutas avanzado
Endpoints API y server logic
Data fetching y patrones de carga
Arquitectura de renderizado granular (Partial/Hydration Strategies)
Integración con estilos y CSS
Performance, caching y optimización de build
Integración con bases de datos y servicios externos
Middleware y hooks
Configuración avanzada de proyecto
Despliegue y adaptadores
Testing
DevTools y DX

A continuación se presenta una nota expandida, organizada y sin repetir lo anterior.

Astro — Conceptos avanzados y arquitectura extendida

Rutas y Estructura de Navegación

Sistema basado en archivos dentro de src/pages.
Rutas dinámicas mediante [param].astro.
Rutas anidadas simplemente ubicando carpetas dentro de pages.
Soporte para catch-all con [...slug].astro.
Posibilidad de mezclar páginas .astro, .md, .mdx, .js, .ts.
Rutas de API disponibles en el mismo sistema de archivos.

Ejemplo de ruta dinámica

---
export async function getStaticPaths() {
	return [
		{ params: { id: "1" } },
		{ params: { id: "2" } }
	];
}

export async function get({ params }) {
	return {
		body: `ID: ${params.id}`
	};
}
---

API Endpoints y lógica servidor

Archivos .js o .ts dentro de src/pages/api.
Permiten crear:
- Endpoints REST
- Webhooks
- Lógica de backend simple
Totalmente compatibles con adaptadores SSR y plataformas serverless.

Ejemplo de endpoint API

export function get() {
	return new Response(JSON.stringify({ ok: true }), {
		headers: { "Content-Type": "application/json" }
	});
}

Data Fetching

Carga de datos en servidor en el frontmatter (---) de los archivos .astro.
Integración con fetch nativo.
Compatible con getStaticPaths, get y SSR puro.
No envía JS extra al cliente a menos que se use un “island”.

Ejemplo de data fetching en `.astro`

---
const res = await fetch("https://api.example.com/posts");
const posts = await res.json();
---
<ul>
	{posts.map(post => <li>{post.title}</li>)}
</ul>

Estrategias de Hidratación Avanzada

Además de client:load, client:idle, client:visible existen nuevas estrategias:
- client:media — hidrata según media-queries.
- client:hover — hidrata al interactuar con hover.
Permiten controlar con precisión cuánta interactividad carga el usuario.
Combinables con múltiples frameworks simultáneamente.

Estilos y CSS

Soporte integrado para:
- CSS global (src/styles)
- CSS Scoped dentro de .astro
- Tailwind (config oficial)
- PostCSS y Sass
- CSS Modules
Cada .astro puede contener estilos encapsulados.

Ejemplo de CSS Scoped

<style>
	h1 {
		color: var(--accent);
	}
</style>

Performance y Optimización

Astro produce HTML estático ultra-optimizado.
Minimiza JS por defecto.
Optimiza imágenes automáticamente con @astrojs/image.
Integración con:
- Prefetch automático de rutas
- Carga diferida de componentes
- Caching inteligente por adaptador
Build final altamente estable y con tree-shaking aplicado a islands.

Integración con Bases de Datos y Servicios

Usando SSR o endpoints API:
- Conexiones a PostgreSQL, MySQL, MongoDB, Redis, Supabase, etc.
En SSG:
- Astro genera el contenido en build-time usando fetch o SDKs.

Middleware y Hooks

Middleware global mediante src/middleware.js.
Permite:
- Autenticación
- Reescritura de rutas
- Inyección de headers
- Validación de acceso
Hooks integrados en astro.config.mjs (build, dev, pre-render, etc.).

Ejemplo de middleware simple

export async function onRequest({ request, locals, url }, next) {
	if (url.pathname.startsWith("/admin") && !locals.user) {
		return new Response("Unauthorized", { status: 401 });
	}
	return next();
}

Configuración Avanzada (`astro.config.mjs`)

Personalización de:
- Integraciones
- Adaptadores
- Pre-render
- Markdown
- Aliases
- Server config
Integraciones oficiales: React, Vue, Svelte, Tailwind, MDX, Sitemap, Partytown, Solid.

Alias útil

alias: {
	"@components": "./src/components",
	"@lib": "./src/lib"
}

Despliegues y Adaptadores (ampliado)

No repetimos lo mencionado antes, sino que añadimos:

Static — genera HTML sin servidor (el modo más rápido).
Node SSR — para proyectos grandes con backend tradicional.
Edge — ejecuta en Cloudflare y otros entornos edge.
Hybrid Render — páginas mezcladas entre SSG y SSR.
Auto-inyección de headers, streaming, caching y compatibilidad con Edge Functions.

Testing y Calidad

Testing recomendado:
- Vitest para lógica interna.
- Playwright para e2e.
- @astrojs/test para componentes .astro.
Integración con TypeScript estricta.
Tipado automático de contenido con astro:content.

Herramientas de Desarrollo

Astro Dev Tools (extensión navegador).
Vista de rutas en tiempo real.
Inspección de islands y rutas.
Logs detallados de SSR y compilación.

Nota complementaria: conceptos que completan la arquitectura de Astro

Fragmentos (<Fragment />) para composición sin nodos extra.
Slots avanzados: múltiples, nombrados y anidados.
Prerender a nivel de página con export const prerender = true;.
Streaming SSR renderizando HTML progresivo.
Static redirects y server redirects.
Hybrid islands combinando frameworks dentro del mismo componente.

Si deseas puedo generar:

Una nota separada solo para “SSR y arquitectura de renderizado”.
Un glosario de conceptos completo.
Una nota práctica con patrones de uso reales.
Una guía de migración desde Next.js o Vite SPA.