ZephyrCloudIO/zephyr-packages

Configurar Astro para Zephyr

Configuração

Leia o astro.config.* existente do site, seu modo output e adaptador, e a versão instalada do astro antes de editar. Mantenha suas integrações e opções existentes. Se zephyr-astro-integration estiver faltando, instale-o apenas quando alterações de dependência forem autorizadas; ele é necessário apenas em tempo de build, portanto uma dependência de desenvolvimento é suficiente.

O pacote instalado declara um peer do astro de ^4.0.0 || ^5.15.8 || ^6.4.6 || ^7.0.7 e usa a versão do Vite que o Astro fornece. Adicione withZephyr() como a última entrada em 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()],
});

O Astro executa os hooks astro:build:done uma integração por vez na ordem da lista, e o Zephyr faz o upload a partir desse hook. Listá-lo por último permite que arquivos escritos por integrações anteriores, como um sitemap, existam antes do upload. A exportação padrão é a mesma função withZephyr. Não adicione vite-plugin-zephyr também a vite.plugins; a integração já gerencia a publicação.

Module Federation

Esta integração não configura Module Federation e não resolve zephyr:dependencies em URLs remotas. Suas opções mfConfigs e federation são metadados de publicação encaminhados inalterados e são necessários apenas para pacotes TAP. Leia detalhes de publicação antes de defini-los. O guia compartilhado zephyr-module-federation cobre o modelo de host e remoto entre projetos.

Apenas saída estática

A integração faz upload do diretório que o Astro passa para astro:build:done e nunca envia um entrypoint de servidor ou tipo de snapshot. Esse diretório é a saída do cliente, portanto publica um site estático. Com output: 'server' ou um adaptador, apenas arquivos do cliente e pré-renderizados são publicados; rotas sob demanda, endpoints de API e middleware não são. Não apresente esta integração como um caminho de implantação SSR e não remova o adaptador do usuário para encaixá-lo sem autorização; relate a limitação.

A integração também carrega valores ZE_PUBLIC_* dos arquivos .env do site e reescreve leituras de import.meta.env.ZE_PUBLIC_* e process.env.ZE_PUBLIC_* para que ambientes possam substituí-los após o build. O guia compartilhado zephyr-core cobre esse modelo.

Evite correções enganosas

• Não trate um astro build bem-sucedido como publicação. Erros do Zephyr no hook de build são registrados e o build continua a menos que ZE_FAIL_BUILD=true esteja definido; apenas um target inválido lança uma exceção imediatamente.
• Não defina target: 'tap-app' em um site comum. TAP desabilita a reescrita de ZE_PUBLIC_* e requer metadados de federação emparelhados.
• Não presuma que source maps são publicados; arquivos .map são ignorados para sites comuns.
• Não coloque credenciais em ZE_PUBLIC_*; esses valores são visíveis ao cliente.

Verificar conclusão

Execute o build autorizado com o executor de pacotes existente do site. Confirme se o diretório de saída contém as páginas e assets esperados, e que o Zephyr relata uma publicação bem-sucedida com uma URL de versão. Um build sem credenciais pode estabelecer a correção da saída local, mas não o sucesso da implantação ao vivo. Relate essa distinção e afirme claramente quando rotas renderizadas pelo servidor estão fora do que foi publicado.

Em caso de falha, mantenha o erro acionável e corrija a configuração correspondente. Não altere silenciosamente o modo de saída do site, suprima erros ou afirme que um build parcial foi implantado.