> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/contributor/contributor-pt/guias-para-colaboradores/dependency-management.md).

# Gestão de dependências

Este documento define as práticas recomendadas para gerenciar dependências em projetos JavaScript/TypeScript em todo o ecossistema da Decentraland. Ele se aplica a front-end, back-end, SDKs, bibliotecas compartilhadas e qualquer pacote baseado em npm/yarn/pnpm.

> **Resumo rápido**:
>
> * **Estratégia de versões** → Use **versões exatas/fixas** para `dependencies` (segurança) e `devDependencies` (ambiente de desenvolvimento consistente). Use **intervalos de versão** apenas para `peerDependencies` (flexibilidade).
> * **Exceção** → Pacotes da Decentraland (`@dcl/*`, `decentraland-*`) podem usar intervalos de versão (`^`) por serem pacotes internos confiáveis.
> * **Bibliotecas/pacotes compartilhados** → Use `peerDependencies` com intervalos de versão (^) para bibliotecas compartilhadas (React, @dcl/schemas, etc.). Use `dependencies` com versões exatas apenas para utilitários seguros para duplicar.
> * **Apps/serviços finais** → Use `dependencies` com versões exatas para pacotes de runtime (React, ethers, etc.).

## 1. Justificativa

Muitas bibliotecas dependem de singletons globais, React Context, identidade de classe, caches compartilhados, enums de schema ou pools de DB compartilhados. Instalar várias versões da mesma biblioteca pode causar:

* Contexto não compartilhado entre cópias
* Caches ou pools duplicados
* Verificações instanceof falhando
* Incompatibilidades de enum/symbol
* Aumento do tamanho do bundle
* Bugs de runtime difíceis de diagnosticar

O gerenciamento correto de dependências evita esses problemas.

### Não objetivos

Este padrão não **não** tenta:

* Impor um único gerenciador de pacotes (npm, yarn e pnpm são todos suportados)
* Garantir uma única cópia física em `node_modules` (o foco está na deduplicação de runtime/bundle)

## 2. Definições

| Campo                  | Objetivo                                                                 | Responsabilidade do consumidor                                  | Aplica-se a             |
| ---------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------- | ----------------------- |
| `dependencies`         | Pacotes usados internamente pelo módulo                                  | Nenhum - não se espera que o consumidor os forneça              | Apps e bibliotecas      |
| `peerDependencies`     | Pacotes que devem resolver para uma única versão efetiva em runtime      | Deve instalá-los (ou usar peerDependenciesMeta para opcionais)  | **Somente bibliotecas** |
| `peerDependenciesMeta` | Metadados para peerDependencies, usados para marcar peers como opcionais | Nenhum - afeta apenas o comportamento do gerenciador de pacotes | **Somente bibliotecas** |
| `devDependencies`      | Ferramentas usadas apenas durante o desenvolvimento                      | Nenhum                                                          | Apps e bibliotecas      |

### Sobre peerDependenciesMeta

`peerDependenciesMeta` é um campo que fornece metadados sobre o seu `peerDependencies`. O caso de uso mais comum é marcar peers como **opcionais**:

* **Peers obrigatórios** (padrão): O gerenciador de pacotes avisará se não estiver instalado
* **Peers opcionais**: O gerenciador de pacotes não avisará se estiverem ausentes; seu pacote deve lidar com a ausência deles de forma graciosa

Isso é útil para pacotes que podem funcionar com ou sem certas dependências (por exemplo, um utilitário que funciona com ou sem React, ou uma biblioteca que suporta múltiplos provedores Web3).

### Apps vs Bibliotecas

**Bibliotecas / Pacotes Compartilhados:**

* Use `peerDependencies` para pacotes que devem resolver para uma única versão efetiva em runtime (React, ethers, @dcl/schemas)
* O consumidor (app) fornece essas dependências
* Impede instalações duplicadas e conflitos de singleton

**Apps / Serviços Finais:**

* Costumam usar `dependencies` para pacotes de runtime (React, ethers, etc.)
* Eles são o consumidor final, então a duplicação não é uma preocupação
* `peerDependencies` ainda é válido se o app puder ser consumido como dependência

## 3. Quando usar cada campo

> **Referência rápida**: Veja [Seção 4](#4-examples) para pacotes comuns e sua colocação recomendada.

### Use peerDependencies para (somente bibliotecas):

**Em bibliotecas/pacotes compartilhados**, use `peerDependencies` para pacotes que devem resolver para uma única versão efetiva em runtime:

* React, Redux, wagmi, ethers, viem
* @dcl/schemas e bibliotecas semelhantes entre ecossistemas
* decentraland/connect
* Drivers de DB quando compartilhando pools
* Qualquer biblioteca que dependa de singletons ou contexto

✅ Correto (Biblioteca):

```json
{
  "peerDependencies": {
    "react": "^18.0.0",
    "@dcl/schemas": "^20.0.0"
  }
}
```

❌ Incorreto (Biblioteca usando dependencies para bibliotecas compartilhadas):

```json
{
  "dependencies": {
    "react": "^18.0.0"
  }
}
```

### Use dependencies para:

* Utilitários seguros para duplicar (lodash-es, date-fns)
* **Em apps**: Pacotes de runtime como React, ethers (quando o app é o consumidor final)

> **Importante**: Use sempre **versões exatas/fixas** em `dependencies` para segurança.

✅ Correto (Biblioteca):

```json
{
  "dependencies": {
    "lodash-es": "4.17.21",
    "date-fns": "3.6.0"
  }
}
```

✅ Correto (App):

```json
{
  "dependencies": {
    "react": "18.3.1",
    "ethers": "6.13.0",
    "lodash-es": "4.17.21"
  }
}
```

### peerDependencies opcionais (peerDependenciesMeta)

Para pacotes reutilizáveis que funcionam com ou sem certas dependências, use `peerDependenciesMeta` para marcar peers como opcionais:

✅ Correto:

```json
{
  "peerDependencies": {
    "react": "^18.0.0",
    "ethers": "^6.0.0"
  },
  "peerDependenciesMeta": {
    "ethers": {
      "optional": true
    }
  }
}
```

**O que isso significa:**

* `react` é **obrigatório**: O consumidor deve instalá-lo ou o gerenciador de pacotes avisará
* `ethers` é **opcionais**: O consumidor não precisa instalá-lo; seu pacote deve verificar sua presença antes de usá-lo

**Casos de uso:**

* Pacotes que funcionam tanto em ambientes React quanto não React
* Bibliotecas que suportam múltiplos provedores Web3 (ethers, viem, etc.)
* Utilitários que aprimoram outras bibliotecas, mas não são obrigatórios

### Use devDependencies para:

* Ferramentas (TypeScript, ESLint, testadores, bundlers)

> **Importante**: Use sempre **versões exatas/fixas** em `devDependencies` para garantir um ambiente de desenvolvimento consistente em toda a equipe.

✅ Correto:

```json
{
  "devDependencies": {
    "typescript": "5.4.5",
    "eslint": "8.57.0",
    "vitest": "1.6.0"
  }
}
```

## 4. Exemplos

### Pacotes que DEVEM ser peerDependencies (contexto compartilhado / singletons)

* `react`, `react-dom`, `react-redux`, `react-router-dom`
* `redux`, `@reduxjs/toolkit`
* `ethers`, `viem`, `wagmi`
* `@dcl/schemas`, `@dcl/ui-env`, `@dcl/crypto`
* `decentraland-dapps`, `decentraland-ui`, `decentraland-ui2`, `decentraland-connect`
* `pg`, `pg-pool`

### Pacotes que DEVEM ser dependencies (seguros para duplicar)

* `lodash-es`, `date-fns`
* `uuid`, `nanoid`
* `zod`, `ajv`
* `ms`, `mitt`, `fp-future`

## 5. Padrões relacionados

* [Padrões de Teste](/contributor/contributor-pt/guias-para-colaboradores/testing-standards.md)
* [Padrões de UI](https://github.com/decentraland/docs/tree/main/contributor/contributor-guides/ui-standards/README.md)
* [Padrões de UI Web](https://github.com/decentraland/docs/tree/main/contributor/contributor-guides/web-ui-standards/README.md)
* [WKC Architecture](https://github.com/decentraland/docs/tree/main/contributor/contributor-guides/well-known-components/README.md)
* [Diretrizes de documentação da API](/contributor/contributor-pt/guias-para-colaboradores/api-documentation.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/contributor/contributor-pt/guias-para-colaboradores/dependency-management.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.