FW Writing Astro

¿Qué hace FW Writing Astro?

Alcance y decisiones iniciales

Usa esta habilidad para componentes, enrutamiento, contenido, renderizado e integraciones específicos de Astro. No la uses para prescribir internos de React, una arquitectura de backend o un proveedor de despliegue; combina la habilidad del framework/entorno relevante solo cuando sea necesario.

Antes de editar, inspecciona package.json, el archivo de bloqueo, las versiones de Astro y el adaptador, astro.config.*, tsconfig, las rutas/maquetaciones/configuración de contenido existentes y los scripts del repositorio. Sigue la documentación de la versión instalada y las convenciones existentes. No instales integraciones, actualices dependencias, despliegues o llames a servicios de pago sin autorización.

• Prefiere HTML prerenderizado para el contenido que se puede construir por adelantado. El frontmatter se ejecuta en tiempo de construcción para rutas prerenderizadas, y en el servidor para rutas bajo demanda; no es código de navegador.
• Usa SSR para requisitos reales en tiempo de solicitud, como contenido autenticado o datos frescos. Requiere un adaptador compatible. En versiones que soportan el modelo actual, la salida estática predeterminada puede optar por rutas individuales a SSR con export const prerender = false; output: 'server' hace que SSR sea el valor predeterminado y permite excepciones con prerender = true. Versiones anteriores tienen una configuración híbrida diferente: inspecciona antes de migrar.
• Un sitio completamente estático normalmente no necesita adaptador. No equipares Astro con Cloudflare ni impongas SSR en contenido estático.
• Preserva la accesibilidad, el escapado y los límites de confianza. No interpoles HTML no confiable con set:html; desinfecta el renderizado de formato confiable en su límite de entrada real.

Componentes nativos y props válidos

Usa componentes .astro para maquetación y contenido estático. Declara Props cuando un componente acepte props; las páginas sin props no necesitan una interfaz ceremonial. Usa los atributos reales del elemento, reenvía los atributos deliberadamente y evita una etiqueta polimórfica con conjuntos de atributos incompatibles. Una tarjeta enlazada puede usar un enlace dentro de un artículo en lugar de enviar href a un artículo. No anides controles interactivos dentro de un ancla envolvente.

ASTRO-CARD — src/components/Card.astro completo; no requiere biblioteca CSS:

---
import type { HTMLAttributes } from 'astro/types';

interface Props extends Omit<HTMLAttributes<'article'>, 'title'> {
  title: string;
  description?: string;
  href?: string;
}

const { title, description, href, class: className, ...rest } = Astro.props;
---

<article {...rest} class:list={['card', className]}>
  <h2>{href ? <a href={href}>{title}</a> : title}</h2>
  {description && <p>{description}</p>}
  <slot />
</article>

Usa slots con nombre para regiones de contenido explícitas y class:list para clases condicionales. Valida los destinos de enlaces no confiables por separado; un tipo string no es una validación de URL.

Comportamiento pequeño en el navegador antes que islands del framework

Usa primero HTML semántico (details, formularios nativos), luego un <script> pequeño procesado cuando se necesite comportamiento en el navegador. No agregues React/Vue/Svelte solo para alternar un menú. Los scripts de Astro se agrupan/deduplican; selecciona todas las instancias del componente o usa un elemento personalizado con ámbito. Con navegación del lado del cliente, sigue el ciclo de vida del enrutador instalado y evita oyentes duplicados. Los valores del frontmatter no están disponibles automáticamente en los scripts del navegador; pasa solo datos no secretos a través de atributos DOM explícitos o props.

ASTRO-BUTTON — src/components/Counter.astro completo, para navegación ordinaria de página completa:

<button type="button" data-counter aria-label="Incrementar cuenta">0</button>
<script>
  document.querySelectorAll<HTMLButtonElement>('button[data-counter]').forEach((button) => {
    let count = 0;
    button.addEventListener('click', () => {
      button.textContent = String(++count);
    });
  });
</script>

Usa un island del framework cuando los componentes existentes del framework o un estado interactivo sustancial lo justifiquen, con una integración ya instalada. Elige client:load para comportamiento necesario de inmediato, client:idle para comportamiento no crítico, client:visible para contenido fuera de pantalla y client:media para un requisito real dependiente de medios. Los componentes sin una directiva client:* renderizan HTML sin hidratación del framework. client:only omite el renderizado del servidor y necesita una experiencia de carga/fallback intencional, no una solución genérica.

Colecciones de Contenido siguen la versión instalada

Usa colecciones para contenido estructurado repetido, no para cada página aislada. Inspecciona la configuración existente y los identificadores de entrada antes de editar:

• Astro 5 introdujo el modelo de cargador (loader) de la Capa de Contenido, normalmente en src/content.config.ts. Los proyectos heredados pueden usar src/content/config.ts y type: 'content' en lugar de cargadores. Estas ubicaciones/APIs de archivo no son intercambiables.
• Verifica la exportación de Zod instalada. El siguiente ejemplo apunta a la exportación z de Astro 5 desde astro:content; la documentación actual usa astro/zod. No reemplaces mecánicamente las importaciones en una versión que carezca de ese módulo.
• Las entradas del cargador usan id; no asumas las APIs heredadas slug o entry.render(). Para el renderizado de la Capa de Contenido, usa el helper render(entry) soportado. MDX requiere su integración si se incluyen archivos MDX.

ASTRO-COLLECTION-V5 — src/content.config.ts completo para Astro 5 con entradas Markdown locales:

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

ASTRO-COLLECTION-LIST — página completa src/pages/blog/index.astro, emparejada con esa colección y al menos una entrada Markdown válida según el esquema:

---
import { getCollection } from 'astro:content';
const posts = await getCollection('blog', ({ data }) => !import.meta.env.PROD || !data.draft);
posts.sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
---
<h1>Blog</h1>
<ul>{posts.map((post) => <li>{post.data.title}</li>)}</ul>

Esta lista deliberadamente no inventa URLs de páginas de detalle. Si agregas enlaces, implementa rutas dinámicas coincidentes y getStaticPaths() para páginas prerenderizadas. Verifica los borradores tanto en las rutas de detalle como en los listados; filtrar solo el índice no es control de acceso. El contenido privado en tiempo de solicitud no debe filtrarse a través de la salida de compilación o cachés públicas.

Coherencia de configuración regional, canónica y 404

Elige la política de URL antes de cambiar rutas: el site de producción configurado, la base de despliegue, el formato de barra inclinada/compilación, los prefijos regionales, el comportamiento de la raíz y el comportamiento de fallback deben coincidir con los archivos reales y las redirecciones del host.

• Usa rutas basadas en carpetas. Con prefixDefaultLocale: false, las páginas en el idioma predeterminado viven en la raíz; otros idiomas tienen carpetas. Con true, todos los idiomas tienen carpetas regionales y el índice raíz aún necesita un manejo intencional.
• Usa los helpers astro:i18n compatibles con la versión cuando sea útil. La configuración no traduce el contenido ni crea páginas faltantes. Enlaza solo traducciones existentes; preserva una ruta equivalente significativa al cambiar de idioma.
• Los canónicos deben usar el origen de producción y la ruta canónica elegida, no el host/parámetros de consulta arbitrarios de la solicitud de Astro.url.href. Establece site para el despliegue; ten en cuenta base y la normalización de la barra inclinada final. Establece el lang del documento y emite alternativas hreflang solo para equivalentes reales con enlaces recíprocos. No canonices todos los idiomas al inglés.
• Implementa src/pages/404.astro cuando se necesite una página de error personalizada. En rutas SSR, devuelve un estado 404 real, no un cuerpo de error exitoso. En alojamiento estático, verifica que el archivo 404 generado se sirva con estado 404. No uses fallback de SPA para un sitio de varias páginas ni redirijas cada ruta de idioma faltante a la página de inicio. Evita indexar páginas de error y no le des a cada URL faltante un auto-canónico.

ASTRO-CANONICAL-FRAGMENT — ejemplo parcial de maquetación, no una página independiente. Asume que site está configurado y que la ruta actual ya cumple con la política de base/idioma/barra del repositorio:

---
if (!Astro.site) throw new Error('Configura la URL del sitio de producción');
const canonical = new URL(Astro.url.pathname, Astro.site);
---
<link rel="canonical" href={canonical} />

Activos y límites de despliegue

Prefiere src/assets/ y Image de astro:assets para imágenes que se beneficien de procesamiento. Mantén activos que requieran URLs sin cambios, robots.txt e íconos en public/; la etiqueta <img> ordinaria es válida para casos de paso directo/remoto deliberados. Proporciona alt significativo (vacío para imágenes decorativas) y dimensiones intrínsecas o restricciones de maquetación equivalentes. Empareja las APIs de imagen responsiva con la versión instalada y evita cargar cada imagen con impaciencia; prioriza solo las imágenes críticas genuinamente visibles en la parte superior. Verifica los servicios de imagen SSR y sus requisitos de tiempo de ejecución/costo antes de habilitarlos.

Usa los mecanismos de cabeceras/redirecciones del host existente solo cuando sea necesario. _headers y _redirects son específicos del proveedor, no requisitos universales de Astro. Para SSR del adaptador, sigue la salida generada y las convenciones de enlace en tiempo de ejecución de esa versión del adaptador, en lugar de una configuración estática/SPA genérica escrita a mano.

Verificación e informes

Usa los scripts existentes de verificación/compilación/prueba del repositorio cuando esté autorizado. Verifica la tipificación de props, las rutas emitidas, la validación de la colección, la exposición de páginas de detalle de borradores, los enlaces de cambio de idioma, el origen canónico/eliminación de consultas, el comportamiento de base/barra, el estado de rutas desconocidas, el comportamiento del teclado y los errores de la consola del navegador. Una compilación estática exitosa no prueba la compatibilidad en tiempo de ejecución SSR ni las redirecciones de producción. Informa los comandos realmente ejecutados, las suposiciones de versión, las integraciones/componentes de contenido faltantes y el comportamiento de alojamiento no verificado. No instales, despliegues ni actives servicios remotos como un paso de verificación implícito.

Fuentes y procedencia

Esta es la síntesis del autor, no una copia masiva de habilidades de terceros. Lee solo la documentación relevante para la tarea y la versión instalada:

• Astro oficial: componentes y props, scripts del navegador, renderizado bajo demanda.
• Astro oficial: Colecciones de Contenido, migración a Astro 5, enrutamiento i18n, adaptador de Cloudflare.
• astrolicious/agent-skills es una referencia comunitaria, no documentación oficial de Astro ni una garantía de compatibilidad. Consúltalo de forma selectiva; la documentación oficial de API coincidente con la versión tiene prioridad.