# Desarrollo y recarga

Servidor nativo, modo Vite, compilación real, rutas y comportamiento del shell Astro.

Consulta las versiones, cambios y requisitos en [Framework 4.0 y CLI 1.2](/es/docs/guides/releases/).


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

## Arrancar el servidor

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

El modo predeterminado es nativo. Abre un listener HTTP en `127.0.0.1` y sirve shell y microapps bajo el mismo origen. El servidor no ofrece un flag `--host` en el parser de esta versión.

| Opción | Efecto |
| --- | --- |
| `--port <n>`, `-p <n>` | Puerto HTTP del modo nativo |
| `--native` | Selecciona el servidor Zig; es el defecto |
| `--vite` | Selecciona supervisión de procesos por app |
| `--open`, `-o` | Solicita apertura del navegador en modo nativo |
| `--no-open` | Evita apertura en modo nativo |

Si `--native` y `--vite` aparecen juntos, la última selección prevalece. Un valor de puerto que no puede convertirse a `u16` deja de ser una sobrescritura válida y se utiliza la configuración. El conflicto real de puerto informa el número y termina con salida 1.

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

## Qué sirve cada ruta

| Ruta | Contenido |
| --- | --- |
| `/` y páginas del shell | Fuentes del shell o su build Astro/Next |
| `/mf-busqueda/src/main.tsx` | Módulo compilado de esa microapp |
| `/@modules/<specifier>` | Dependencias npm resueltas para el navegador |
| `/@wu/apps.json` | Catálogo del proyecto en desarrollo |
| `/@wu/client.js` | Cliente de recarga inyectado |
| `/__wu_ws` | Canal WebSocket de recarga |
| `/__wu_hmr` | Canal SSE alternativo |

Las rutas son parte del servidor, no endpoints de negocio de la aplicación. Evita ocupar esos prefijos con páginas del producto. La resolución usa el directorio de la app para encontrar dependencias y aplicar las entradas de `.wu-deps.json`.

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

## Compilación bajo demanda

WU resuelve un archivo cuando el navegador lo solicita, aplica el compilador correspondiente y reescribe imports para que sean URLs cargables. La capa de transformación contempla imports npm, alias de fuente `@/` y `~/` y imports CSS.

Vue y Svelte usan sus compiladores; Solid su transformación y Qwik su optimizador. Angular mantiene un programa TypeScript y un contexto esbuild incrementales. TypeScript y JSX requieren herramientas Node del proyecto; ya no existe el transformador JSX nativo desactivado de versiones anteriores.

El protocolo del daemon es multiplexado y un pool compila módulos en paralelo. La caché incluye versiones de compiladores, lockfiles, `.wu-deps.json` y tsconfig; la primera ejecución tras actualizar recompila. Los logs están en `.wu-cache/wu-compiler.log`. Un error o timeout devuelve HTTP `500` con overlay y reinicia el daemon cuando corresponde.

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

## Controles del compilador

`WU_COMPILE_TIMEOUT_MS` fija el plazo de compilación, 30000 ms por defecto. `WU_COMPILE_WORKERS` fija los daemons, con defecto `min(CPU, 4)` y máximo `16`. `WU_COMPILE_PREFETCH=0` desactiva la compilación anticipada de imports. Estas variables configuran el proceso que inicia `wu dev`.

Las dependencias se preempaquetan con esbuild en `.wu-cache/deps/` y sus URLs versionadas son inmutables. Archivos del proyecto y módulos compilados usan ETags y revalidación `304`. Los archivos estáticos admiten HEAD y un rango de bytes (`206`/`416`); JSON solicitado con fetch o atributos de import conserva su MIME JSON.

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

## Cambios y recarga

El watcher incorpora directorios creados después del arranque y usa una cola numerada de eventos. Cada módulo tiene su versión: una edición invalida el módulo y sus importadores hasta la entrada de app. Los módulos intactos conservan instancia; un cambio compartido remonta las apps afectadas. La pérdida de eventos o el reinicio del servidor provoca recarga completa. La conservación del estado local depende del framework y del cambio.

Un shell Astro o Next es un caso especial: WU sirve `shell/dist/` o `shell/out/`. En el primer arranque intenta construirlo si falta `index.html`. Los cambios posteriores disparan reconstrucción antes de recargar. Si falla el build inicial, las microapps pueden seguir sirviéndose, pero el shell dará 404 hasta corregir su comando de build.

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

## Modo Vite

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

Esta rama crea un proceso para el shell y otro por microapp, usando sus `dev_cmd` y puertos declarados. Añade `--port` a cada comando. Si una app tiene toolchain local, intenta ejecutar el Vite de esa app.

La rama recibe la configuración, no el puerto ni la apertura calculados para el servidor nativo. Por tanto, no esperes que `wu dev --vite --port 3200` cambie todos los puertos ni cree el listener unificado del modo nativo. Usa el modo Vite cuando necesites comprobar el comportamiento de la toolchain específica del proyecto.

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

## Túneles y variables de entorno

Por defecto se aceptan Host `localhost`, `*.localhost` e IPs literales. CORS y HMR rechazan orígenes externos. Para un túnel, declara el hostname exacto sin esquema ni puerto; guardar la configuración aplica la lista sin reiniciar. `*.example.com` acepta subdominios, no el dominio base. Evita comodines de proveedores compartidos.

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

Desde 1.1.0, solo las claves `.env` con prefijo `VITE_` o `WU_` llegan a `import.meta.env`, tanto en desarrollo como en build nativo. Una clave privada devuelve `undefined` y genera un aviso. Migra únicamente valores públicos: antes `API_URL` / `import.meta.env.API_URL`; después `VITE_API_URL` / `import.meta.env.VITE_API_URL`. Mantén secretos en el backend.

Las rutas de archivos, módulos, sourcemaps y manifiestos comprueban límites de proyecto o paquete y enlaces simbólicos. `.env`, metadatos VCS y claves siguen bloqueados con `?raw`, `?import` o `?inline`; esos sufijos no permiten leer archivos privados.

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

## Diagnóstico rápido

Una página vacía requiere mirar la primera solicitud de módulo fallida y la consola del navegador. Comprueba `wu.json`, nombre de registro, grants y entradas, además del proceso del servidor. Si el error es de compilación, busca la causa en la salida de WU y en el log del daemon. Si aparece una app omitida, su directorio falta o está duplicado en la configuración.

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

## Referencia de implementación

- `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`