Referência de Astro, Next e helpers

Escolher uma entrada do pacote

Os componentes Astro são importados de wu-framework/integrations/astro/*.astro. A factory de astro.config fica em wu-framework/integrations/astro. No Next, você pode usar o barrel wu-framework/integrations/next ou seus subcaminhos WuShell, WuApp, WuAppSSR e WuMount.

WuShell inicia o catálogo, WuApp monta no cliente e WuAppSSR compõe HTML inicial com uma ponte de hidratação. Um componente de UI não constitui um registro remoto adicional: mantenha os mesmos nomes de apps no servidor, no catálogo e na entrada do navegador.

Os exemplos Astro usam frontmatter e os de Next, JSX. A receita de servidor mostra sua composição com módulos SSR. Para funções auxiliares, importe explicitamente o nome indicado de wu-framework.

wuIntegration

Configura Vite e injeta a inicialização cliente a partir de astro.config.

wuIntegration(options?): AstroIntegration

• Parâmetros: apps, sandbox, cdn e debug.
• Retorno: Objeto de integração Astro com hook astro:config:setup.
• Erros: Trate falhas de registro ou carregamento do módulo; os componentes podem registrar erros no console conforme seu contrato.
• Permissões: O host controla o catálogo e a política do WU. A integração não concede capacidades às aplicações por si só.
• Limpeza: Mantenha uma instância de shell por documento e desmonte as aplicações quando seu host for removido.

import { defineConfig } from 'astro/config';
import wuIntegration from 'wu-framework/integrations/astro';
export default defineConfig({ integrations: [wuIntegration({ apps: [{ name: 'card', url: '/apps/card' }], sandbox: 'module' })] });

cdn adiciona um script UMD ao head, mas a inicialização automática das apps continua importando o pacote wu-framework. Escolher CDN aqui não substitui automaticamente essa importação.

Referência: integrations/astro/index.js.

Astro WuShell

Emite a configuração do catálogo e executa wu.init em um script cliente.

<WuShell apps={apps} sandbox? debug?>children</WuShell>

• Parâmetros: apps obrigatória; sandbox e debug. Renderiza seu slot.
• Retorno: Markup Astro com configuração JSON e script empacotado.
• Erros: Trate falhas de registro ou carregamento do módulo; os componentes podem registrar erros no console conforme seu contrato.
• Permissões: O host controla o catálogo e a política do WU. A integração não concede capacidades às aplicações por si só.
• Limpeza: Mantenha uma instância de shell por documento e desmonte as aplicações quando seu host for removido.

---
import WuShell from 'wu-framework/integrations/astro/WuShell.astro';
---
<WuShell apps={[{ name: 'card', url: '/apps/card' }]}><main>Contenido</main></WuShell>

Não é um provedor reativo: alterar um atributo HTML não atualiza a configuração do runtime nem cria uma segunda instância.

Referência: integrations/astro/WuShell.astro.

Astro WuApp

Emite um ponto de montagem cliente para uma aplicação registrada.

<WuApp name="card" lazy? class? style? />

• Parâmetros: name; lazy ativa IntersectionObserver; class e style do contêiner.
• Retorno: Contêiner Astro e script de montagem.
• Erros: Trate falhas de registro ou carregamento do módulo; os componentes podem registrar erros no console conforme seu contrato.
• Permissões: O host controla o catálogo e a política do WU. A integração não concede capacidades às aplicações por si só.
• Limpeza: Mantenha uma instância de shell por documento e desmonte as aplicações quando seu host for removido.

---
import WuApp from 'wu-framework/integrations/astro/WuApp.astro';
---
<WuApp name="card" lazy />

Inicialize e registre a aplicação por um shell ou integração. O componente não recebe module nem renderiza SSR.

Referência: integrations/astro/WuApp.astro.

Astro WuAppSSR

Renderiza uma aplicação no Astro SSR ou SSG e publica props para hidratação opcional.

<WuAppSSR name module props? styles? hydrate? fallbackToClient? />

• Parâmetros: module servidor obrigatório; hydrate e fallbackToClient true; class/style opcionais.
• Retorno: HTML inicial com marcador de SSR e estado JSON quando há hidratação.
• Erros: Trate falhas de registro ou carregamento do módulo; os componentes podem registrar erros no console conforme seu contrato.
• Permissões: O host controla o catálogo e a política do WU. A integração não concede capacidades às aplicações por si só.
• Limpeza: Mantenha uma instância de shell por documento e desmonte as aplicações quando seu host for removido.

---
import WuAppSSR from 'wu-framework/integrations/astro/WuAppSSR.astro';
import { renderHtml } from 'wu-framework/server';
const module = renderHtml(() => '<p>Resumen</p>');
---
<WuAppSSR name="card" module={module} hydrate={false} />

hydrate:false mantém apenas o HTML do servidor. fallbackToClient:false propaga o erro SSR. O componente não expõe todas as opções nonce/shadowMode de renderApp.

Referência: integrations/astro/WuAppSSR.astro.

Next WuShell

Inicializa o runtime no cliente e coordena seus descendentes com a promise do shell.

WuShell({apps, sandbox?, debug?, children?}): ReactNode

• Parâmetros: apps e children; sandbox/debug.
• Retorno: children sem um wrapper DOM adicional.
• Erros: Trate falhas de registro ou carregamento do módulo; os componentes podem registrar erros no console conforme seu contrato.
• Permissões: O host controla o catálogo e a política do WU. A integração não concede capacidades às aplicações por si só.
• Limpeza: Mantenha uma instância de shell por documento e desmonte as aplicações quando seu host for removido.

import { WuShell } from 'wu-framework/integrations/next';
export default function Layout({ children }) {
  return <WuShell apps={[{ name: 'card', url: '/apps/card' }]}>{children}</WuShell>;
}

A inicialização é executada uma vez por montagem do shell. Alterar apps depois não reconfigura automaticamente o catálogo.

Referência: integrations/next/WuShell.js.

Next WuApp

Monta uma app WU por um componente cliente do Next.

WuApp({name, appName?, lazy?, ...props}): ReactNode

• Parâmetros: Nome registrado, lazy, className/style, onMount/onUnmount e props adicionais.
• Retorno: Elemento de host gerenciado pelo React.
• Erros: Trate falhas de registro ou carregamento do módulo; os componentes podem registrar erros no console conforme seu contrato.
• Permissões: O host controla o catálogo e a política do WU. A integração não concede capacidades às aplicações por si só.
• Limpeza: Mantenha uma instância de shell por documento e desmonte as aplicações quando seu host for removido.

import { WuApp } from 'wu-framework/integrations/next';
export default function Page() { return <WuApp name="card" lazy />; }

Importe o subcaminho da integração, não WuApp do runtime: este último é um wrapper imperativo diferente.

Referência: integrations/next/WuApp.js.

Next WuAppSSR

Renderiza o módulo de servidor e adiciona a ponte cliente quando hydrate é true.

WuAppSSR({name, module, props?, ...options}): Promise<ReactNode>

• Parâmetros: module obrigatório; props, styles, shadowMode, hydrate true, fallbackToClient true.
• Retorno: Árvore React com o HTML SSR e a ponte WuMount opcional.
• Erros: Trate falhas de registro ou carregamento do módulo; os componentes podem registrar erros no console conforme seu contrato.
• Permissões: O host controla o catálogo e a política do WU. A integração não concede capacidades às aplicações por si só.
• Limpeza: Mantenha uma instância de shell por documento e desmonte as aplicações quando seu host for removido.

import { WuAppSSR } from 'wu-framework/integrations/next';
import { renderHtml } from 'wu-framework/server';
const module = renderHtml(() => '<p>Resumen</p>');
export default async function Page() {
  return <WuAppSSR name="card" module={module} hydrate={false} />;
}

O bundle do navegador deve registrar um hydrate compatível para adotar o DOM; um renderizador de servidor não fornece esse ciclo de vida automaticamente.

Referência: integrations/next/WuAppSSR.js.

Next WuMount

Conecta um contêiner existente do servidor à montagem ou hidratação do core.

WuMount({name, containerId, props?, ssr?}): null

• Parâmetros: name, id de um elemento já existente, props opcionais e ssr true.
• Retorno: null; realiza apenas efeitos cliente.
• Erros: Trate falhas de registro ou carregamento do módulo; os componentes podem registrar erros no console conforme seu contrato.
• Permissões: O host controla o catálogo e a política do WU. A integração não concede capacidades às aplicações por si só.
• Limpeza: O efeito desmonta ao ser removido e também reverte um mount que termine após o cancelamento. Não destrói o singleton.

import WuMount from 'wu-framework/integrations/next/WuMount';
const bridge = <WuMount name="card" containerId="wu-app-card" props={{ count: 1 }} />;

props é publicado antes da montagem; props não figura nas dependências do efeito, então alterá-lo não representa um canal reativo de update.

Referência: integrations/next/WuMount.js.

parseVersion

Decompõe uma versão para os contratos versionados.

parseVersion(version): [number, number, number]

• Parâmetros: Valor convertido em string; remove os prefixos v/=, prerelease e build. Componentes não numéricos são convertidos em 0.
• Retorno: Tupla [major,minor,patch].
• Erros: Não é um validador estrito: uma versão não numérica pode produzir [0,0,0].
• Permissões: Função utilitária sem concessões nem acesso privilegiado próprio.
• Limpeza: Não cria recursos persistentes.

import { parseVersion } from 'wu-framework';
console.log(parseVersion('1.2.3'));

Usa a mesma semântica de contracts; não substitui todas as regras de node-semver.

Referência: src/core/wu-semver.js.

compareVersions

Compara estruturas de versões para ordenar a compatibilidade.

compareVersions(a, b): number

• Parâmetros: Duas strings de versão ou tuplas [major,minor,patch].
• Retorno: Valor negativo, zero ou positivo.
• Erros: Valida conforme sua implementação; não equivale a um parser geral de pacotes.
• Permissões: Função utilitária sem concessões nem acesso privilegiado próprio.
• Limpeza: Não cria recursos persistentes.

import { compareVersions, parseVersion } from 'wu-framework';
console.log(compareVersions(parseVersion('1.0.0'), parseVersion('2.0.0')));

Referência: src/core/wu-semver.js.

satisfies

Verifica um intervalo de versão aceito pelos contratos WU.

satisfies(version, range): boolean

• Parâmetros: Versão e intervalo em strings.
• Retorno: Boolean.
• Erros: Valida conforme sua implementação; não equivale a um parser geral de pacotes.
• Permissões: Função utilitária sem concessões nem acesso privilegiado próprio.
• Limpeza: Não cria recursos persistentes.

import { satisfies } from 'wu-framework';
console.log(satisfies('1.2.3', '^1.0.0'));

Os operadores compatíveis são os implementados pelo WU; não pressuponha suporte completo à gramática npm.

Referência: src/core/wu-semver.js.

silenceAllLogs

Desativa os níveis do logger central do framework.

silenceAllLogs(): void

• Parâmetros: Sem argumentos.
• Retorno: void.
• Erros: Valida conforme sua implementação; não equivale a um parser geral de pacotes.
• Permissões: Função utilitária sem concessões nem acesso privilegiado próprio.
• Limpeza: Não cria recursos persistentes.

import { silenceAllLogs } from 'wu-framework';
silenceAllLogs();

Não intercepta todo o console do navegador nem garante silenciar o console de adaptadores ou aplicações.

Referência: src/index.js.

enableAllLogs

Ativa os níveis do logger central do framework.

enableAllLogs(): void

• Parâmetros: Sem argumentos.
• Retorno: void.
• Erros: Valida conforme sua implementação; não equivale a um parser geral de pacotes.
• Permissões: Função utilitária sem concessões nem acesso privilegiado próprio.
• Limpeza: Não cria recursos persistentes.

import { enableAllLogs } from 'wu-framework';
enableAllLogs();

Controla o logger central compartilhado desse módulo importado.

Referência: src/index.js.