Introducción

Astro Base Framework Moderno

Astro es el framework web que combina lo mejor del contenido estático con componentes interactivos, ofreciendo:

Rendimiento máximo con cero JS por defecto
Arquitectura de islas para hidratación selectiva
Multi-framework (React, Svelte, Vue y más)
Contenido organizado con colecciones tipadas

Arquitectura de Islas

Cada isla es un componente interactivo que se hidrata independientemente en páginas estáticas, optimizando rendimiento y SEO.

HTML Estático

Isla React

Isla Vue

Isla Svelte

Logo

Inicio Productos Contacto

Bienvenido a nuestra tienda

Contenido estático de alto rendimiento

Listado de productos

Producto 1

Producto 2

Producto 3

Producto 4

🏝️ Carrito de compras (React)

3 items | Total: $299

🏝️ Buscador (Vue)

🔍 Buscar productos...

🏝️ Recomendaciones (Svelte)

Productos sugeridos

Comunicación entre Islas en Astro

Las islas en Astro son componentes interactivos que se hidratan de forma independiente. Para compartir estado entre ellas, debes usar estos patrones específicos:

Event Bus

Comunicación mediante eventos personalizados del navegador, ideales para interacciones simples entre componentes.

ejemplo-event-bus.astro

// Emisor (Vue)

const emitEvent = () => {

  window.dispatchEvent(new CustomEvent('cart-updated', {

    detail: { items: cartItems }

  }));

// Receptor (React)

useEffect(() => {

  const handler = (e) => setItems(e.detail.items);

  window.addEventListener('cart-updated', handler);

  return () => window.removeEventListener('cart-updated', handler);

}, []);

Cuándo usar: Actualizaciones de carrito, notificaciones entre componentes

Global State

Stores agnósticas que funcionan en cualquier framework (Nanostores, Zustand).

ejemplo-global-state.astro

// store.js

import { atom } from 'nanostores';

export const $cart = atom([]);

// Isla React

import { $cart } from './store';

useEffect(() => $cart.subscribe(setItems), []);

// Isla Svelte

import { $cart } from './store';

$: items = $cart.get();

Cuándo usar: Estado compartido como carrito, autenticación, temas

URL State

Estado persistente en la URL que todas las islas pueden leer.

ejemplo-url-state.astro

// Lectura

const params = new URLSearchParams(location.search);

const category = params.get('category');

// Escritura

const updateFilters = (newFilters) => {

  const params = new URLSearchParams(newFilters);

  history.pushState({}, '', `?${params.toString()}`);

Cuándo usar: Filtros, paginación, parámetros compartibles

Patrones que NO funcionan

ref.current entre componentes de diferentes islas
Context API de React entre frameworks distintos
Stores específicas (Vuex, Svelte stores) entre islas
Comunicación directa entre componentes de diferentes frameworks

¿Qué son las Directivas?

Las directivas son atributos especiales de HTML disponibles dentro del maquetado de los componentes de Astro (archivos .astro). Controlan el comportamiento de elementos y componentes de manera específica.

Reglas para Directivas

Deben incluir dos puntos : en su nombre (formato X:Y)
Deben ser visibles para el compilador
Ejemplo: client:load, class:list

Directivas de Astro

Directivas Comunes

Directiva	Propósito	Detalles
`class:list`	Convierte un array de clases en un string de clases CSS	string: Se agrega al elemento Object: Keys verdaderas se agregan Array: Se aplana Valores falsy se omiten
`set:html`	Inyecta un string de HTML	⚠️ Advertencia: Astro no verifica el valor (riesgo XSS)
`set:text`	Inyecta texto de forma segura	Equivalente a `innerText`

Directivas del Cliente

Directiva	Propósito	Prioridad	Uso típico
`client:load`	Hidrata inmediatamente al cargar	Alta	UI visible e interactiva desde el inicio
`client:idle`	Hidrata cuando el navegador está inactivo	Media	UI de menor prioridad
`client:visible`	Hidrata al entrar en el viewport	Baja	Elementos fuera del viewport inicial
`client:media`	Hidrata si se cumple media query	Baja	Elementos dependientes del tamaño de pantalla
`client:only`	Renderiza solo en el cliente	-	Para frameworks específicos (React, Vue, etc.)

Otras Directivas

Directiva	Propósito	Detalles
`server:defer`	Convierte en isla de servidor	Renderizado bajo demanda
`is:global`	Aplica estilos CSS globalmente	No solo al componente
`is:inline`	Evita procesamiento de Astro	No se empaquetan, no se deduplican
`define:vars`	Pasa variables del servidor	Solo JSON-serializables, implica `is:inline`
`is:raw`	Trata hijos como texto plano	Ignora sintaxis de Astro

Ejemplo de Directiva class:list

Ejemplo Interactivo de class:list

Cambia los controles para ver cómo class:list genera las clases CSS dinámicamente

Controles Interactivos

Activo Error

Tamaño del Botón

Vista Previa:

Estado Actual

Variables de Estado

const isActive = true;

const hasError = ;

const size = "small";

Código class:list

Código generado

<button class:list={[
  'btn',
  'transition-all',
  'duration-200',
  'rounded-md',
  {
  'bg-blue-500 text-white': isActive && !hasError,
  'bg-red-500 text-white': hasError,
  'bg-gray-300 text-gray-600': !isActive && !hasError,
  'px-2 py-1 text-sm': size === 'small',
  'px-4 py-2': size === 'medium',
  'px-6 py-3 text-lg': size === 'large'
  }
]}>
  Botón Dinámico
</button>

Código Oculto

Haz clic en "Ver código generado" para mostrar cómo class:list construye las clases CSS dinámicamente

Content Collections Tu Base de Datos de Contenido

Gestiona tu Contenido como un Pro

las Content Collections son la forma más poderosa de organizar y validar contenido en Astro. Con TypeScript automático y validación de esquemas, transforman tu contenido en una base de datos tipada.

¿Qué son las Content Collections?

Content collections son la mejor forma de gestionar conjuntos de contenido en cualquier proyecto Astro. Las Collections ayudan a organizar y consultar tus documentos, habilitan Intellisense y la comprobación de tipos en tu editor, y proporcionan seguridad de tipos TypeScript automática para todo tu contenido.

Piensa en ellas como tu base de datos de archivos con superpoderes: validación automática, tipos de TypeScript y consultas optimizadas.

Estructura típica:

estructura-proyecto

src/

└──content/

├──blog/ ← Colección "blog"

│ ├──post-1.md

│ └──post-2.md

├──projects/ ← Colección "projects"

│ ├──project-a.md

│ └──project-b.md

└──config.ts ← Configuración y schemas

Validación Automática

Zod valida tus frontmatter automáticamente

TypeScript

Tipos automáticos sin configuración extra

Rendimiento SSG

Todo se procesa en build time

¿Cuándo usar Content Collections?

Blog o documentación

✅ Recomendado

Perfecto para contenido markdown con metadatos estructurados

Portfolio de proyectos

✅ Recomendado

Organiza proyectos con imágenes, tecnologías y descripciones

Contenido desde CMS

✅ Recomendado

Con loaders puedes conectar Contentful, Strapi, etc.

Páginas simples estáticas

❌ Considera otras opciones

Para pocas páginas sin estructura, usa páginas normales

Nuevo en Astro 5.10: Live Content Collections

Astro 5.10 introduce una nueva función experimental: live content collections. Esta potente incorporación te permite obtener contenido en tiempo de ejecución en lugar de en tiempo de compilación, lo que abre nuevas posibilidades para el contenido dinámico y en tiempo real.

Perfecto para: Contenido que se actualiza con frecuencia desde CMS, API, bases de datos u otras fuentes mediante una API unificada, sin necesidad de reconstruir su sitio cuando los datos cambian.

Se debe habilitar en el archivo astro.config.mjs:

astro.config.mjs

export default defineConfig({
        experimental: {
          liveContentCollections: true
      }
      });

Implementación Paso a Paso

1 Define tu Schema (config.ts)

Cualquier documento que no coincida con el esquema no se agregará.

src/content/config.ts

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blogCollection = defineCollection({
  type: 'content', // v2.5.0 y posteriores
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    description: z.string(),
    author: z.string(),
    tags: z.array(z.string()).optional(),
    image: z.object({
      url: z.string(),
      alt: z.string()
    }).optional(),
  }),
});

export const collections = {
  'blog': blogCollection,
};

2 Usa tus Collections

blog.astro

---
// En tu página .astro
import { getCollection } from 'astro:content';
import Layout from '../layouts/Layout.astro';

const blogPosts = await getCollection('blog');
const sortedPosts = blogPosts.sort(
  (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
);
---

<Layout title="Blog">
  <div class="blog-list">
    {sortedPosts.map((post) => (
      <article class="post-card">
        <h2>
          <a href={`/blog/${post.slug}`}>
            {post.data.title}
          </a>
        </h2>
        <p>{post.data.description}</p>
        <time>{post.data.pubDate.toDateString()}</time>
      </article>
    ))}
  </div>
</Layout>

3 Astro 5.0+: Content Loaders

config.ts - Con Loaders

// src/content/config.ts - Astro 5.0+
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blogCollection = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/data/blog' }),
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    tags: z.array(z.string()),
  }),
});

// Con API externa
const newsCollection = defineCollection({
  loader: async () => {
    const response = await fetch('https://api.example.com/news');
    const articles = await response.json();
    
    return articles.map(article => ({
      id: article.id,
      title: article.title,
      content: article.content,
      pubDate: new Date(article.date),
    }));
  },
  schema: z.object({
    title: z.string(),
    content: z.string(),
    pubDate: z.date(),
  }),
});

💡 Los loaders te permiten cargar contenido desde cualquier fuente: APIs, bases de datos, archivos en diferentes ubicaciones, etc.

Astro Base Framework Moderno

Arquitectura de Islas

Bienvenido a nuestra tienda

Categorías

Listado de productos

🏝️ Carrito de compras (React)

🏝️ Buscador (Vue)

🏝️ Recomendaciones (Svelte)

Comunicación entre Islas en Astro

Event Bus

Global State

URL State

Patrones que NO funcionan

¿Qué son las Directivas?

Reglas para Directivas

Directivas de Astro

Directivas Comunes

Directivas del Cliente

Otras Directivas

Ejemplo de Directiva class:list

Controles Interactivos

Vista Previa:

Estado Actual

Código class:list

Código Oculto

Gestiona tu Contenido como un Pro

¿Qué son las Content Collections?

Estructura típica:

Validación Automática

TypeScript

Rendimiento SSG

¿Cuándo usar Content Collections?

Blog o documentación

Portfolio de proyectos

Contenido desde CMS

Páginas simples estáticas

Nuevo en Astro 5.10: Live Content Collections

Implementación Paso a Paso

1 Define tu Schema (config.ts)

2 Usa tus Collections

3 Astro 5.0+: Content Loaders

¿Content Collections o qué?

Páginas .astro normales

✅ Ventajas:

❌ Desventajas:

Live Collections o SSR

✅ Ventajas:

❌ Desventajas:

Decisión Rápida