# Configuration and discovery

Fields actually read from wu.config.json, ports, commands, and mounting metadata.

See versions, changes and requirements in [Framework 4.0 and CLI 1.2](/docs/guides/releases/).


<span id="archivo-de-proyecto"></span>

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

## Project file

Commands look for `wu.config.json` in the working directory. There is no global `--config` flag or `wu config` command. Paths are interpreted from the root where the CLI runs.

```json
{
  "name": "conocimiento",
  "version": "1.1.0",
  "shell": {
    "dir": "shell",
    "framework": "astro",
    "port": 4321,
    "dev_cmd": "npx astro dev",
    "build_cmd": "npx astro build"
  },
  "apps": [
    {
      "name": "busqueda",
      "dir": "mf-busqueda",
      "framework": "react",
      "port": 5001,
      "dev_cmd": "npx vite",
      "build_cmd": "npx vite build"
    },
    {
      "name": "explorador",
      "dir": "mf-explorador",
      "framework": "vue",
      "port": 5002
    }
  ],
  "proxy": {
    "port": 3000,
    "open_browser": false,
    "/api": {
      "target": "http://127.0.0.1:8080",
      "rewrite": true,
      "cors": false
    }
  },
  "shared": ["react", "react-dom/client"],
  "security": {
    "enabled": true
  }
}
```

`version` is configuration metadata. The executable still uses the version compiled into `main.zig`; editing that field does not update the CLI.

<span id="shell-y-aplicaciones"></span>

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

## Shell and applications

| Field | Default value | Usage |
| --- | --- | --- |
| `shell.dir` | `shell` | Host directory |
| `shell.framework` | `vanilla` | Selects shell handling |
| `shell.port` | `4321` | Process port in Vite mode |
| `shell.dev_cmd` | Empty string | Shell command in Vite mode |
| `shell.build_cmd` | Empty string | Falls back to Astro, Next, or Vite according to framework |
| `apps[].name` | Empty string | App identifier for the catalog |
| `apps[].dir` | Empty string | Local directory and override key |
| `apps[].framework` | `vanilla` | Compiler/template selection |
| `apps[].port` | `0` | App port in Vite mode |
| `apps[].dev_cmd` | `npx vite` | Legacy development command |
| `apps[].build_cmd` | `npx vite build` | Build command |

The parser accepts only the fields it consumes. It does not validate a complete topology as a strict schema would: many values with the wrong type retain the default. Declare names, directories, and ports explicitly, and review the result with `wu info`.

<span id="metadatos-que-llegan-al-navegador"></span>

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

## Metadata reaching the browser

| Field in each app | Values / meaning |
| --- | --- |
| `fullBleed` or `full_bleed` | Boolean allowing the shell to grant full width |
| `domOwnership` or `dom_ownership` | `wu`, `app`, or `light` |
| `nativeShadow` or `native_shadow` | Optional legacy alias; explicit ownership is preferable |
| `grants` | Maximum list of capabilities granted by the host |
| `compatibility` | `strict` or `v2` |

These fields travel into the development catalog and build output. A host grant does not replace the corresponding request in `wu.json`. `fullBleed` communicates a presentation preference; the shell must consume it when laying out the container.

<span id="proxy-y-puertos"></span>

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

## Proxy and ports

In native mode, port priority is `wu dev --port`, then `proxy.port`, then 3000. Browser-opening priority is `--open` or `--no-open`, then `proxy.open_browser`, which defaults to `true`.

Each `proxy` key starting with `/` defines a rule. It can be a string containing the destination origin or an object with `target`, `rewrite`, and `cors`. `rewrite: true` removes the prefix: `/api/users` is forwarded as `/users`. `cors` is optional.

The implemented proxy supports `http://` origins; it rejects TLS/`https://`, credentials, and ambiguous destinations. Do not declare a URL containing paths as though it were an origin. `shell` and `apps` ports belong to Vite process mode; they do not create separate listeners in the native server.

<span id="opciones-nuevas-de-desarrollo-y-build"></span>

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

## New development and build settings

```json
{
  "dev": { "allowedHosts": ["mi-tunel.example.com"] },
  "build": { "keepPreviousBuilds": 2 },
  "security": { "upgradeInsecureRequests": false }
}
```

`dev.allowedHosts` (`allowed_hosts`) extends permitted hosts for Host, CORS and WebSocket; it does not change the listening interface. `build.keepPreviousBuilds` (`keep_previous_builds`) retains hashed files from previous builds, defaulting to `2`. `security.upgradeInsecureRequests` (`upgrade_insecure_requests`) explicitly sets the CSP directive; when absent, WU omits it if `hsts` is `off` or configured origins use HTTP.

Configuration reloads preserve grants, manifest mode and layout settings. Newly added apps enter the router and watcher; an unchanged save does not force a reload. Directories `./mf-a` or `mf-a/` normalize to `mf-a`.

<span id="descubrimiento-automático"></span>

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

## Automatic discovery

If the file is missing, several commands inspect immediate subdirectories and recognize project and dependency signals. Only a directory named exactly `shell` becomes the shell. Other candidates are treated as microapps.

Discovery recognizes the imported adapter and exact dependency names: Preact is not mistaken for React, and Qwik/Stencil are detected. It sorts directories and assigns free ports from 5001 without colliding with the shell; explicit ports are respected.

Detection uses heuristics; it does not reproduce the entire template matrix or replace the intent of an explicit manifest. Malformed JSON reports an error and disables discovery to avoid operating on an accidental topology. Fix the file before continuing.

CLI `1.2.0` accepts `manifest: "define"` on each app and `security.frameOrigins` for remote iframes. Frame origins only enter `frame-src`; they do not enable host scripts or connections. The catalog navigation filter does not block fetch access. See [remote apps](/docs/framework/remote-apps/) and [build](/docs/cli/build/).

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

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

## Implementation references

- `wu-cli/src/config/config.zig`
- `wu-cli/src/config/discovery.zig`
- `wu-cli/src/runtime/allowed_hosts.zig`
- `wu-cli/src/runtime/dev/config_reload.zig`
- `wu-cli/src/runtime/handlers/proxy.zig`