Eminence Astro Suite
- Astro
- TypeScript
- Cloudflare Workers
¿Por qué existe?
En mis proyectos de Astro acababa repitiendo la misma configuración de metadatos una y otra vez. Las herramientas SEO que encontraba se quedaban cortas en algunas cosas o añadían demasiado relleno para lo que necesitaba.
Quería una solución que empujara hacia las buenas prácticas sin encerrarte en ellas cuando un caso concreto necesita otra cosa. Y quería que la experiencia de desarrollo fuera tan buena como Astro permite, no una capa más que hay que pelearse para añadir un título o una imagen social.
¿Qué hace?
Eminence Astro Suite reúne los metadatos de una página y los archivos relacionados con SEO en una misma integración para Astro. Configuras los valores comunes una vez y los componentes los usan de forma consistente en el sitio.
La integración crea el módulo virtual de Vite que necesitan los componentes en runtime. Puede generar iconos desde un SVG o una imagen de 512×512, y se encarga del flujo para humans.txt, robots.txt, security.txt y el sitemap mediante la integración original de Astro.
Para la mayoría de sitios basta con usar Head. Mientras haces la página, empiezas con un título y una descripción y te concentras en construirla. Cuando necesites más, añades Open Graph o JSON-LD a las props del layout y listo: se completan automáticamente las etiquetas globales que configuraste en la integración. También genera los archivos relacionados, para que no tengas que repetir información más de lo necesario.
También delimita el alcance a propósito: evita etiquetas y salidas obsoletas en lugar de acumularlas por si acaso.
¿Cómo lo construí?
Lo planteé primero como una integración y después como componentes. Así la configuración global vive en un solo sitio y los componentes no tienen que inventar sus propios defaults. El módulo virtual de Vite conecta ambas partes y mantiene esa configuración disponible en runtime.
El repositorio combina una web de documentación con un paquete de componentes para Astro que también es una integración. En vez de tratarlo como una colección de etiquetas independientes, busqué que los valores compartidos, los componentes de <head> y los archivos generados formaran un flujo único.
Stack
- Astro
- TypeScript
- Cloudflare Workers para la web de documentación
Las partes difíciles
La primera dificultad fue la estructura del proyecto. Tener una web de documentación, un paquete de componentes para Astro y una integración de Astro dentro del mismo trabajo hace que el desarrollo no sea el de un sitio o una librería normal. Me obligó a pensar con cuidado dónde vivía cada responsabilidad y cómo probar el conjunto sin perder la separación entre partes.
Después vino decidir qué etiquetas soportar. Leí todas las etiquetas de <head>, sus atributos, por qué existen y si siguen siendo precisos o relevantes. Pasé horas investigando, probando en sitios reales, revisando las buenas prácticas de Google, RFCs, MDN y la Metadata API de Next.js para ver también cómo lo resuelven otros. Documenté la decisión detrás de cada etiqueta en la web de documentación. No quería presentar como una buena práctica algo que ya está desactualizado. La lección fue que reducir superficie no es dejar funciones fuera por pereza: es mantener una API que pueda defender.
También profundicé en la generación de archivos y en TypeScript. Quería ofrecer el máximo autocompletado y tipado posible sin añadir comprobaciones de runtime innecesarias que afectaran al rendimiento. Eso llevó a trabajar casos límite complejos de tipos y a distinguir qué se podía garantizar durante el desarrollo de lo que realmente debía validarse al ejecutar.
Por último, la suite tenía que funcionar sin casarse con un adaptador y ser compatible tanto con sitios estáticos como con SSR. Ese límite condicionó las decisiones de integración y me recordó que la comodidad de una plataforma no debe convertirse en una dependencia oculta.
Impacto
Por ahora la uso yo. Está en beta: funciona tal como está, pero todavía quiero terminar mejoras y puedo introducir cambios incompatibles antes de considerarla finalizada.
Es un proyecto open source. Si también te cansa repetir la configuración de metadatos en Astro, puedes probarlo, revisar el enfoque y abrir una issue si encuentras un caso que la suite todavía no cubre bien.