# Dependências e versões por app

O que wu install agrega, como resolve versões major e quando cria toolchains locais.

<span id="instalar-desde-declaraciones-de-cada-parte"></span>

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

## Instalar a partir das declarações de cada parte

```bash
wu install
```

`wu i` é um alias. O comando agrega as declarações do shell e das apps, edita o manifesto raiz e chama npm. Adiciona `wu-framework` e `esbuild` do catálogo se ninguém os declarar. `wu add` e o assistente de `wu create` usam o mesmo instalador.

Adicione dependências à microapp que precisa delas ou ao shell que as consome e execute `wu install` novamente. Executar apenas `npm install` na raiz não recalcula o agregado nem `.wu-deps.json`.

<span id="resolución-de-bibliotecas"></span>

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

## Resolução de bibliotecas

Intervalos compatíveis são intersectados: `^19.0.0` e `^19.3.0` produzem `^19.3.0`. Grupos incompatíveis usam aliases; o grupo mais novo mantém o nome principal. O resolvedor distingue linhas 0.x (`zone.js--0.15`) e versões fixas incompatíveis no mesmo major (`lodash--4.17.20`). Cada pacote aparece em uma única seção raiz; `dependencies` prevalece se alguma app o declarar ali.

```json
{
  "dependencies": {
    "react": "^19.0.0",
    "react--17": "npm:react@^17.0.0"
  }
}
```

O mapa de overrides vincula cada import original ao alias correto:

```json
{
  "mf-legacy": {
    "react": "react--17"
  }
}
```

As chaves são diretórios, como `mf-legacy`, e não nomes de catálogo, como `legacy`. O desenvolvimento e o build carregam esse mapa. Isso não significa que todos os consumidores de React compartilhem uma única instância: cada conjunto compatível deve resolver a identidade correta.

A resolução aceita `^`, `~`, comparadores, versões exatas, curingas, versões parciais, intervalos com hífen e até 32 alternativas `||`. Não aplica a regra adicional do npm que limita pré-lançamentos à mesma tripla do comparador: confira a versão instalada ao usar pré-lançamentos. Valores não SemVer, como dist-tags ou URLs Git, são mantidos como pins explícitos e declarações diferentes geram um aviso.

<span id="identidad-de-módulos-en-desarrollo"></span>

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

## Identidade dos módulos em desenvolvimento

Cada import é resolvido a partir do arquivo que o declara, respeitando `node_modules` locais e aninhados, pnpm, links e `.wu-deps.json`. As URLs identificam versão e localização. Pacotes em `shared`, e sempre `wu-framework`, são resolvidos na raiz como uma só instância; uma cópia local incompatível gera um aviso. Não coloque em `shared` uma biblioteca que precise coexistir em versões diferentes.

<span id="toolchains-distintas"></span>

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

## Toolchains diferentes

Vite, plugins e outras ferramentas de compilação precisam de uma estratégia diferente. O algoritmo escolhe a versão major com mais declarações entre as apps que ainda compartilham a raiz; os empates favorecem a maior. As aplicações incompatíveis passam para a instalação local. A decisão se repete porque remover os votos de uma app pode mudar outra maioria.

```json
{
  "mf-vite-antiguo": {
    "_toolchain": "local"
  }
}
```

A CLI instala dentro dessa app, e o build usa seu `node_modules/vite`. O mapa é regravado a cada instalação ou excluído se não restarem overrides. As árvores locais gerenciadas pelo WU carregam informações de procedência para que possam ser removidas quando deixarem de ser necessárias.

<span id="dependencias-locales"></span>

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

## Dependências locais

Uma declaração `file:` é preservada e reexpressa a partir da raiz. Por exemplo, `file:../ui` dentro de `mf-panel/package.json` se torna um caminho para `ui/` a partir do manifesto agregado. As declarações `link:` e `workspace:` são omitidas pelo coletor atual; esse mecanismo não implementa um gerenciador completo de workspaces npm.

<span id="reescritura-del-manifiesto-raíz"></span>

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

## Regravação do manifesto da raiz

Um manifesto raiz sem `_wu` é rejeitado com saída `1`. `--force` autoriza seu gerenciamento preservando campos e dependências; se o JSON estiver inválido, substitui o arquivo e mantém o original em `package.json.bak`.

```bash
wu install --force
```

`--force` ou `-f` pertencem ao WU: habilitam a regravação, não são um repasse geral de opções do npm. Não há opções públicas `--frozen-lockfile`, `--offline`, `--no-install` nem seletor de gerenciador de pacotes.

`_wu.managed` registra dependências escritas pelo WU para remover apenas as que nenhuma app declara mais. Scripts próprios, workspaces, overrides, engines e dependências adicionadas manualmente são preservados. `dev` e `build` só são criados quando ausentes. A escrita JSON é atômica com cópia `.bak`; uma marca `_wu` antiga é migrada na primeira instalação.

<span id="migrar-un-proyecto-a-cli-12"></span>

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

## Migrar um projeto para CLI 1.2

`wu update` atualiza a ferramenta global. `wu upgrade` compara o shell e as apps com o catálogo da CLI instalada, que na 1.2.0 propõe WU Framework `^4.0.0`. Revise primeiro a [migração do framework](/pt/docs/guides/releases/): atualizar intervalos não migra automaticamente todas as APIs.

```sh
wu upgrade --dry-run
wu upgrade --json
wu upgrade --yes
wu install
wu doctor --json
wu build
```

Sem flags, `upgrade` mostra o plano e pede confirmação. `--dry-run` não escreve; `--json` só aplica com `--yes`; `--check` retorna `2` quando há mudanças pendentes. Nunca reduz versões: preserva intervalos mais novos ou abertos e protocolos não SemVer. Versões exatas exigem `--force`, que também não permite reduzi-las. Dependências ausentes são informadas sem serem adicionadas. Um erro ou confirmação sem terminal retorna `1`.

As migrações reconhecem templates antigos e salvam `<file>.bak`: tags Stencil únicas, remoção de `@stencil/core` sem uso, shell Astro com APIs DOM, seletores com `CSS.escape`, regras ausentes de `.gitignore` e runtimes Qwik/Svelte em `shared`. As mudanças são idempotentes; fontes personalizadas que não correspondem são mantidas com um aviso. O comando não instala dependências: finalize com `wu install`.

Exemplo de intervalos: `wu-framework: ^3.2.1` declarado passa a `^4.0.0`; `react: ^19.4.0` é preservado porque supera o `^19.3.0` do catálogo; `react: 19.2.0` mantém seu pin salvo com `--force`. Não adicione `_wu.managed` manualmente: `wu install` o mantém.

<span id="salidas-y-errores"></span>

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

## Saídas e erros

JSON inválido na configuração ou no manifesto de uma app interrompe a instalação antes da escrita, com linha, coluna e saída `1`. Falhas de escrita, manifesto raiz externo sem `--force` e falhas do npm na raiz ou em toolchains locais também retornam `1`. Com conflitos de bibliotecas, a chamada raiz inclui `--legacy-peer-deps`.

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

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

## Referência de implementação

- `wu-cli/src/commands/install.zig`
- `wu-cli/src/commands/upgrade.zig`
- `wu-cli/src/commands/codemods.zig`
- `wu-cli/src/config/semver.zig`
- `wu-cli/src/config/json_doc.zig`
- `wu-cli/src/runtime/module_graph.zig`
- `wu-cli/tests/install-preserva.test.cjs`
- `wu-cli/tests/upgrade.test.cjs`
- `wu-cli/tests/dev-module-resolution.test.cjs`