ZephyrCloudIO/zephyr-packages

Configurer Astro pour Zephyr

Configuration

Lisez le fichier astro.config.* existant du site, son mode output et son adaptateur, ainsi que la version installée d'astro avant toute modification. Conservez ses intégrations et options existantes. Si zephyr-astro-integration est manquante, installez-la uniquement lorsque les modifications de dépendances sont autorisées ; elle n'est nécessaire qu'au moment de la build, donc une dépendance de développement est suffisante.

Le package installé déclare un pair astro de ^4.0.0 || ^5.15.8 || ^6.4.6 || ^7.0.7 et utilise la version de Vite fournie par Astro. Ajoutez withZephyr() comme dernière entrée dans 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 exécute les hooks astro:build:done une intégration à la fois dans l'ordre de la liste, et Zephyr télécharge depuis ce hook. Le placer en dernier permet aux fichiers écrits par les intégrations précédentes, comme un sitemap, d'exister avant le téléchargement. L'export par défaut est la même fonction withZephyr. N'ajoutez pas également vite-plugin-zephyr dans vite.plugins ; l'intégration gère déjà la publication.

Federation de modules

Cette intégration ne configure pas la fédération de modules et ne résout pas zephyr:dependencies en URLs distantes. Ses options mfConfigs et federation sont des métadonnées de publication transmises sans modification et ne sont requises que pour les packages TAP. Lisez les détails de publication avant de les définir. Le guide partagé zephyr-module-federation couvre le modèle hôte et distant inter-projets.

Sortie statique uniquement

L'intégration télécharge le répertoire qu'Astro transmet à astro:build:done et n'envoie jamais de point d'entrée serveur ou de type d'instantané. Ce répertoire est la sortie client, donc elle publie un site statique. Avec output: 'server' ou un adaptateur, seuls les fichiers client et pré-rendus sont publiés ; les routes à la demande, les points d'extrémité API et les middleware ne le sont pas. Ne présentez pas cette intégration comme un chemin de déploiement SSR, et ne supprimez pas l'adaptateur de l'utilisateur pour l'adapter sans autorisation ; signalez plutôt la limitation.

L'intégration charge également les valeurs ZE_PUBLIC_* depuis les fichiers .env du site et réécrit les lectures import.meta.env.ZE_PUBLIC_* et process.env.ZE_PUBLIC_* afin que les environnements puissent les remplacer après la build. Le guide partagé zephyr-core couvre ce modèle.

Éviter les correctifs trompeurs

• Ne traitez pas une build astro build réussie comme une publication. Les erreurs Zephyr dans le hook de build sont enregistrées et la build continue sauf si ZE_FAIL_BUILD=true est défini ; seul un target invalide lève une erreur immédiatement.
• Ne définissez pas target: 'tap-app' sur un site ordinaire. TAP désactive la réécriture ZE_PUBLIC_* et nécessite des métadonnées de fédération appairées.
• Ne supposez pas que les source maps sont publiées ; les fichiers .map sont ignorés pour les sites ordinaires.
• Ne placez pas de credentials dans ZE_PUBLIC_* ; ces valeurs sont visibles par le client.

Vérifier l'achèvement

Exécutez la build autorisée avec le gestionnaire de packages existant du site. Confirmez que le répertoire de sortie contient les pages et ressources attendues, et que Zephyr signale une publication réussie avec une URL de version. Une build sans credentials peut établir l'exactitude de la sortie locale, mais pas le succès du déploiement en direct. Signalez cette distinction, et indiquez clairement quand les routes rendues par le serveur sont en dehors de ce qui a été publié.

En cas d'échec, conservez l'erreur exploitable et corrigez la configuration correspondante. Ne modifiez pas silencieusement le mode de sortie du site, ne supprimez pas les erreurs et ne prétendez pas qu'une build partielle a été déployée.