ZephyrCloudIO/zephyr-packages

Astro für Zephyr konfigurieren

Einrichtung

Lies die vorhandene astro.config.*-Datei der Website, ihren output-Modus und Adapter sowie die installierte astro-Version, bevor du Änderungen vornimmst. Behalte die vorhandenen Integrationen und Optionen bei. Wenn zephyr-astro-integration fehlt, installiere sie nur, wenn Abhängigkeitsänderungen autorisiert sind; sie wird nur zur Build-Zeit benötigt, daher reicht eine Entwicklungsabhängigkeit aus.

Das installierte Paket deklariert einen astro-Peer von ^4.0.0 || ^5.15.8 || ^6.4.6 || ^7.0.7 und verwendet die von Astro bereitgestellte Vite-Version. Füge withZephyr() als letzten Eintrag in integrations hinzu:

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 führt astro:build:done-Hooks nacheinander in der Reihenfolge der Liste aus, und Zephyr lädt von diesem Hook aus hoch. Wenn es zuletzt aufgeführt wird, können Dateien, die von früheren Integrationen geschrieben wurden, wie z. B. eine Sitemap, vor dem Upload vorhanden sein. Der Standardexport ist dieselbe withZephyr-Funktion. Füge vite-plugin-zephyr nicht auch zu vite.plugins hinzu; die Integration übernimmt bereits die Veröffentlichung.

Module Federation

Diese Integration konfiguriert keine Module Federation und löst zephyr:dependencies nicht in Remote-URLs auf. Ihre mfConfigs- und federation-Optionen sind unveränderte Metadaten zur Veröffentlichung und werden nur für TAP-Pakete benötigt. Lies die Veröffentlichungsdetails, bevor du sie setzt. Der gemeinsame Leitfaden zephyr-module-federation behandelt das Host- und Remote-Modell über mehrere Projekte hinweg.

Nur statische Ausgabe

Die Integration lädt das Verzeichnis hoch, das Astro an astro:build:done übergibt, und sendet nie einen Server-Einstiegspunkt oder einen Snapshot-Typ. Dieses Verzeichnis ist die Client-Ausgabe, daher veröffentlicht es eine statische Website. Mit output: 'server' oder einem Adapter werden nur Client- und vorgerenderte Dateien veröffentlicht; On-Demand-Routen, API-Endpunkte und Middleware werden nicht veröffentlicht. Stelle diese Integration nicht als SSR-Deployment-Pfad dar und entferne den Adapter des Benutzers nicht ohne Autorisierung, um ihn anzupassen; melde stattdessen die Einschränkung.

Die Integration lädt auch ZE_PUBLIC_*-Werte aus den .env-Dateien der Website und überschreibt Lesezugriffe auf import.meta.env.ZE_PUBLIC_* und process.env.ZE_PUBLIC_*, sodass Umgebungen sie nach dem Build überschreiben können. Der gemeinsame Leitfaden zephyr-core behandelt dieses Modell.

Irreführende Korrekturen vermeiden

• Behandle einen erfolgreichen astro build nicht als Veröffentlichung. Zephyr-Fehler im Build-Hook werden protokolliert, und der Build wird fortgesetzt, es sei denn, ZE_FAIL_BUILD=true ist gesetzt; nur ein ungültiges target führt sofort zu einem Fehler.
• Setze target: 'tap-app' nicht auf einer normalen Website. TAP deaktiviert die ZE_PUBLIC_*-Überschreibung und erfordert gepaarte Federation-Metadaten.
• Gehe nicht davon aus, dass Source Maps veröffentlicht werden; .map-Dateien werden für normale Websites übersprungen.
• Lege keine Anmeldeinformationen in ZE_PUBLIC_* ab; diese Werte sind clientseitig sichtbar.

Abschluss überprüfen

Führe den autorisierten Build mit dem vorhandenen Paket-Runner der Website aus. Bestätige, dass das Ausgabeverzeichnis die erwarteten Seiten und Assets enthält und dass Zephyr eine erfolgreiche Veröffentlichung mit einer Versions-URL meldet. Ein Build ohne Anmeldeinformationen kann die lokale Korrektheit der Ausgabe bestätigen, aber nicht den Erfolg des Live-Deployments. Weise auf diesen Unterschied hin und gib klar an, wenn serverseitig gerenderte Routen außerhalb des Veröffentlichten liegen.

Im Fehlerfall behalte den umsetzbaren Fehler bei und korrigiere die entsprechende Konfiguration. Ändere nicht stillschweigend den Ausgabemodus der Website, unterdrücke keine Fehler und behaupte nicht, dass ein partieller Build bereitgestellt wurde.