# Desenvolvimento e recarga

Servidor nativo, modo Vite, compilação real, rotas e comportamento do shell Astro.

Veja versões, mudanças e requisitos em [Framework 4.0 e CLI 1.2](/pt/docs/guides/releases/).


<span id="arrancar-el-servidor"></span>

<span class="section-anchor" id="section-1"></span>

## Iniciar o servidor

```bash
wu dev --port 3200 --no-open
```

O modo padrão é nativo. Abre um listener HTTP em `127.0.0.1` e serve o shell e as microapps sob a mesma origem. O servidor não oferece uma flag `--host` no parser desta versão.

| Opção | Efeito |
| --- | --- |
| `--port <n>`, `-p <n>` | Porta HTTP do modo nativo |
| `--native` | Seleciona o servidor Zig; é o padrão |
| `--vite` | Seleciona a supervisão de processos por app |
| `--open`, `-o` | Solicita a abertura do navegador no modo nativo |
| `--no-open` | Evita a abertura no modo nativo |

Se `--native` e `--vite` aparecerem juntos, prevalece a última seleção. Um valor de porta que não pode ser convertido em `u16` deixa de ser uma substituição válida, e a configuração é usada. Um conflito real de porta informa o número e termina com saída 1.

<span id="qué-sirve-cada-ruta"></span>

<span class="section-anchor" id="section-2"></span>

## O que cada rota serve

| Rota | Conteúdo |
| --- | --- |
| `/` e páginas do shell | Fontes do shell ou seu build Astro/Next |
| `/mf-busqueda/src/main.tsx` | Módulo compilado dessa microapp |
| `/@modules/<specifier>` | Dependências npm resolvidas para o navegador |
| `/@wu/apps.json` | Catálogo do projeto em desenvolvimento |
| `/@wu/client.js` | Cliente de recarga injetado |
| `/__wu_ws` | Canal WebSocket de recarga |
| `/__wu_hmr` | Canal SSE alternativo |

As rotas fazem parte do servidor, não são endpoints de negócio da aplicação. Evite ocupar esses prefixos com páginas do produto. A resolução usa o diretório da app para encontrar dependências e aplicar as entradas de `.wu-deps.json`.

<span id="compilación-bajo-demanda"></span>

<span class="section-anchor" id="section-3"></span>

## Compilação sob demanda

O WU resolve um arquivo quando o navegador o solicita, aplica o compilador correspondente e reescreve os imports para que sejam URLs carregáveis. A camada de transformação contempla imports npm, aliases de fonte `@/` e `~/` e imports CSS.

Vue e Svelte usam seus compiladores; Solid usa sua transformação e Qwik seu otimizador. Angular mantém um programa TypeScript e um contexto esbuild incrementais. TypeScript e JSX exigem ferramentas Node do projeto; o transformador JSX nativo desativado de versões anteriores foi removido.

O protocolo do daemon é multiplexado e um pool compila módulos em paralelo. A cache inclui versões dos compiladores, lockfiles, `.wu-deps.json` e tsconfig; a primeira execução após atualizar recompila. Os logs ficam em `.wu-cache/wu-compiler.log`. Um erro ou timeout retorna HTTP `500` com overlay e reinicia o daemon quando necessário.

<span id="controles-del-compilador"></span>

<span class="section-anchor" id="section-4"></span>

## Controles do compilador

`WU_COMPILE_TIMEOUT_MS` define o prazo de compilação, 30000 ms por padrão. `WU_COMPILE_WORKERS` define a quantidade de daemons, com padrão `min(CPU, 4)` e máximo de `16`. `WU_COMPILE_PREFETCH=0` desativa a pré-compilação de imports. Essas variáveis configuram o processo que inicia `wu dev`.

As dependências são pré-empacotadas com esbuild em `.wu-cache/deps/` e suas URLs versionadas são imutáveis. Arquivos do projeto e módulos compilados usam ETags e revalidação `304`. Arquivos estáticos aceitam HEAD e um intervalo de bytes (`206`/`416`); JSON solicitado com fetch ou atributos de import mantém seu MIME JSON.

<span id="cambios-y-recarga"></span>

<span class="section-anchor" id="section-5"></span>

## Mudanças e recarga

O watcher inclui diretórios criados após a inicialização e usa uma fila numerada de eventos. Cada módulo tem sua versão: uma edição invalida o módulo e seus importadores até a entrada da app. Módulos intactos mantêm a instância; uma mudança compartilhada remonta as apps afetadas. Eventos perdidos ou reinício do servidor provocam recarga completa. A preservação do estado local depende do framework e da edição.

Um shell Astro ou Next é um caso especial: o WU serve `shell/dist/` ou `shell/out/`. Na primeira inicialização, tenta construí-lo se `index.html` estiver ausente. As mudanças posteriores disparam uma reconstrução antes da recarga. Se o build inicial falhar, as microapps podem continuar sendo servidas, mas o shell retornará 404 até que seu comando de build seja corrigido.

<span class="section-anchor" id="section-6"></span>

## Modo Vite

```bash
wu dev --vite
```

Esse ramo cria um processo para o shell e outro por microapp, usando seus `dev_cmd` e portas declaradas. Acrescenta `--port` a cada comando. Se uma app tiver uma toolchain local, tenta executar o Vite dessa app.

O ramo recebe a configuração, não a porta nem a abertura calculadas para o servidor nativo. Portanto, não espere que `wu dev --vite --port 3200` altere todas as portas ou crie o listener unificado do modo nativo. Use o modo Vite quando precisar verificar o comportamento da toolchain específica do projeto.

<span id="túneles-y-variables-de-entorno"></span>

<span class="section-anchor" id="section-7"></span>

## Túneis e variáveis de ambiente

Por padrão, os valores Host aceitos são `localhost`, `*.localhost` e IPs literais. CORS e HMR rejeitam origens externas. Para um túnel, declare o hostname exato sem esquema nem porta; salvar a configuração aplica a lista sem reiniciar. `*.example.com` aceita subdomínios, não o domínio base. Evite curingas de provedores compartilhados.

```json
{ "dev": { "allowedHosts": ["mi-tunel.example.com"] } }
```

Desde 1.1.0, apenas chaves `.env` com prefixo `VITE_` ou `WU_` chegam a `import.meta.env`, em desenvolvimento e builds nativos. Uma chave privada retorna `undefined` e gera um aviso. Migre apenas valores públicos: antes `API_URL` / `import.meta.env.API_URL`; depois `VITE_API_URL` / `import.meta.env.VITE_API_URL`. Mantenha segredos no backend.

Rotas de arquivos, módulos, sourcemaps e manifestos verificam os limites do projeto ou pacote e links simbólicos. `.env`, metadados VCS e chaves continuam bloqueados com `?raw`, `?import` ou `?inline`; esses sufixos não permitem ler arquivos privados.

<span class="section-anchor" id="section-8"></span>

## Diagnóstico rápido

Uma página vazia exige examinar a primeira solicitação de módulo que falhou e o console do navegador. Verifique `wu.json`, nome de registro, grants e entradas, além do processo do servidor. Se o erro for de compilação, procure a causa na saída do WU e no log do daemon. Se uma app aparecer como omitida, seu diretório está ausente ou duplicado na configuração.

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-9"></span>

## Referência de implementação

- `wu-cli/src/commands/dev.zig`
- `wu-cli/src/runtime/dev/`
- `wu-cli/src/runtime/compile_pool.zig`
- `wu-cli/src/runtime/compile_warmup.zig`
- `wu-cli/src/runtime/module_graph.zig`
- `wu-cli/tests/dev-security.test.cjs`
- `wu-cli/tests/dev-hmr.test.cjs`
- `wu-cli/tests/dev-compile-concurrency.test.cjs`
- `wu-cli/tests/dev-serving.test.cjs`