APRENDER5 MIN DE LEITURA · MARKDOWN ↗

Sua primeira microapp

Crie um shell Astro com uma microapp React e verifique sua primeira montagem com a CLI 1.2.0.

O que você vai conseguir

Você vai abrir uma página com uma aplicação React e testar seu contador. O WU cuidará de exibir essa aplicação dentro da página. Chamamos isso de montar uma microapp ou microfrontend.

A página que a recebe é o shell. Neste percurso, usaremos Astro no shell e React na microapp; você pode escolher outros frameworks nos seus projetos.

A pasta que reúne ambos se chama workspace. Você a criará com a CLI, o comando wu do terminal. A CLI prepara os arquivos e executa as ferramentas de desenvolvimento; o pacote wu-framework é o runtime que monta as apps no navegador.

1. Preparar o ambiente

Use Node 24 com npm. Abra um terminal na pasta em que deseja criar o projeto e verifique sua versão do Node:

node --version
npm --version

O primeiro comando deve imprimir v24.x.x. Instale a CLI deste percurso e verifique sua versão:

npm install --global @wu-framework/cli@1.2.0
wu --version

O último comando deve imprimir wu 1.2.0. Se wu não for encontrado ou você usar outra versão do Node, consulte Instalação e versões antes de continuar.

2. Criar o shell e o React

O diretório mi-plataforma ainda não deve existir. Execute:

wu create mi-plataforma --template react --shell astro
cd mi-plataforma

O comando gera o shell Astro e uma microapp React. Estas são as partes que você usará:

mi-plataforma/
├── shell/                 # Página anfitriona Astro
├── mf-mi-plataforma/      # Microapp React
├── wu.config.json         # Configuración del workspace
└── package.json

A app se chama mi-plataforma; sua pasta tem o prefixo mf-. Execute os próximos comandos nesta raiz, onde está wu.config.json. A configuração necessária já foi gerada.

3. Instalar e iniciar

Instale as dependências e espere até que o comando termine sem erros:

wu install

Depois, inicie o servidor e deixe o terminal aberto:

wu dev --native --port 3000 --no-open

Quando o terminal anunciar que está escutando, abra http://127.0.0.1:3000. Nesse modo, o WU serve o shell e a microapp na porta 3000. A primeira inicialização também faz o build do shell Astro, por isso pode demorar mais.

4. Verificar sua primeira app

O template da CLI 1.2.0 inclui uma tela inicial e um contador:

Ao abrir a página, procure Overview, Welcome to WU e a app mi-plataforma.
Clique em mi-plataforma na navegação ou no cartão. Devem aparecer React, o nome mi-plataforma e um contador abaixo de Interactions.
Clique em +: o valor passa de 0 para 1. Clique em − para voltar a 0.
Clique em Overview para voltar à tela inicial.

Você já montou uma microapp com WU. Ver seu nome na navegação confirma que ela está registrada; ver o componente e usar o contador confirma que foi carregada e responde.

O componente React que você acabou de usar está em mf-mi-plataforma/src/App.tsx. A página hospedeira está em shell/src/pages/index.astro.

Se algo não aparecer

O que acontece	O que revisar
A porta 3000 está ocupada	Pare o outro servidor ou escolha outra porta com `--port`; abra a URL com esse número.
`wu install` termina com erro	Resolva o primeiro erro do terminal antes de iniciar o servidor. Consulte Diagnóstico.
A página responde 404	Verifique se o build inicial do Astro falhou. O WU estar escutando não garante que o shell tenha sido compilado.
O shell abre, mas React fica vazio	Revise o primeiro erro do console ou de carregamento de JavaScript do navegador. Continue em Desenvolvimento e recarga.

Mais sobre versões, dependências e modo de desenvolvimento

Esta receita usa WU CLI 1.2.0 e Node 24. As dependências do projeto são resolvidas na instalação; a versão da CLI não as fixa. Consulte Versões e distribuição para conhecer as versões cobertas por esta documentação.

wu install reúne dependências do shell e das apps, preserva scripts e metadados personalizados da raiz e executa o gerenciador configurado. Declare cada dependência no pacote que a usa. Veja dependências e catálogos para intervalos compartilhados, conflitos e catálogos.

Com --native, Astro compila o shell em shell/dist/; o WU serve essa saída e a recompila quando o código-fonte muda. Esta receita não inicia outro servidor de desenvolvimento Astro. As portas por app de wu.config.json correspondem ao modo alternativo --vite; a compilação das microapps continua usando ferramentas do Node. Consulte os dois modos.

A diferença entre wu.config.json, wu.json e wu.init() é explicada em O que cada arquivo configura.

Próxima etapa

Continue com Adicionar uma segunda app: você manterá este projeto e montará uma app Vue junto ao React.

Se uma app basta por enquanto, você pode ir diretamente a Preparar a produção para fazer o build e verificar a saída.