ZephyrCloudIO/zephyr-packages

Configurar Astro para Zephyr

Configuración

Lee el astro.config.* existente del sitio, su modo output y adaptador, y la versión instalada de astro antes de editar. Conserva sus integraciones y opciones existentes. Si falta zephyr-astro-integration, instálala solo cuando los cambios de dependencias estén autorizados; solo es necesaria en tiempo de compilación, por lo que una dependencia de desarrollo es suficiente.

El paquete instalado declara un peer de astro de ^4.0.0 || ^5.15.8 || ^6.4.6 || ^7.0.7 y usa la versión de Vite que Astro proporciona. Añade withZephyr() como la última entrada en integrations:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
import { withZephyr } from 'zephyr-astro-integration';

export default defineConfig({
  site: 'https://example.com',
  integrations: [mdx(), sitemap(), withZephyr()],
});

Astro ejecuta los hooks astro:build:done una integración a la vez en orden de lista, y Zephyr sube desde ese hook. Situarlo al final permite que los archivos escritos por integraciones anteriores, como un sitemap, existan antes de la subida. La exportación por defecto es la misma función withZephyr. No añadas también vite-plugin-zephyr a vite.plugins; la integración ya gestiona la publicación.

Module Federation

Esta integración no configura Module Federation y no resuelve zephyr:dependencies en URLs remotas. Sus opciones mfConfigs y federation son metadatos de publicación que se reenvían sin cambios y solo son necesarios para paquetes TAP. Lee los detalles de publicación antes de configurarlos. La guía compartida zephyr-module-federation cubre el modelo de host y remoto entre proyectos.

Solo salida estática

La integración sube el directorio que Astro pasa a astro:build:done y nunca envía un punto de entrada de servidor o tipo de snapshot. Ese directorio es la salida del cliente, por lo que publica un sitio estático. Con output: 'server' o un adaptador, solo se publican archivos de cliente y prerenderizados; las rutas bajo demanda, los endpoints de API y el middleware no se publican. No presentes esta integración como una ruta de despliegue SSR, y no elimines el adaptador del usuario para que encaje sin autorización; informa de la limitación en su lugar.

La integración también carga valores ZE_PUBLIC_* de los archivos .env del sitio y reescribe las lecturas de import.meta.env.ZE_PUBLIC_* y process.env.ZE_PUBLIC_* para que los entornos puedan sobrescribirlos después de la compilación. La guía compartida zephyr-core cubre ese modelo.

Evitar soluciones engañosas

• No trates una compilación astro build exitosa como publicación. Los errores de Zephyr en el hook de compilación se registran y la compilación continúa a menos que se establezca ZE_FAIL_BUILD=true; solo un target inválido lanza una excepción inmediatamente.
• No establezcas target: 'tap-app' en un sitio ordinario. TAP deshabilita la reescritura de ZE_PUBLIC_* y requiere metadatos de federación emparejados.
• No asumas que los mapas de origen se publican; los archivos .map se omiten para sitios ordinarios.
• No pongas credenciales en ZE_PUBLIC_*; esos valores son visibles para el cliente.

Verificar finalización

Ejecuta la compilación autorizada con el ejecutor de paquetes existente del sitio. Confirma que el directorio de salida contiene las páginas y activos esperados, y que Zephyr informa una publicación exitosa con una URL de versión. Una compilación sin credenciales puede establecer la corrección de la salida local, pero no el éxito del despliegue en vivo. Informa de esa distinción y explica claramente cuándo las rutas renderizadas en servidor están fuera de lo que se publicó.

En caso de fallo, conserva el error procesable y corrige la configuración correspondiente. No cambies silenciosamente el modo de salida del sitio, suprimas errores ni afirmes que se desplegó una compilación parcial.