> 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-do-contribuidor/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 Decentraland. Aplica-se a front-end, back-end, SDKs, bibliotecas compartilhadas e qualquer pacote baseado em npm/yarn/pnpm.

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

## 1. Justificativa

Muitas bibliotecas dependem de singletons globais, React Context, identidade de classe, caches compartilhados, enums de schema ou pools de BD compartilhados. Instalar múltiplas versões da mesma biblioteca pode causar:

* Context não compartilhado entre cópias
* Caches ou pools duplicados
* Falhas em verificações instanceof
* Incompatibilidades de enum/símbolo
* Aumento no tamanho do bundle
* Bugs em tempo de execução difíceis de diagnosticar

O gerenciamento correto de dependências previne esses problemas.

### Não-objetivos

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

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

## 2. Definições

| Campo                  | Propósito                                                                     | Responsabilidade do consumidor                                  | Aplica-se a            |
| ---------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------- |
| `dependencies`         | Pacotes usados internamente pelo módulo                                       | Nenhum - o consumidor não é esperado para fornecê-los           | Apps e bibliotecas     |
| `peerDependencies`     | Pacotes que devem resolver para uma única versão efetiva em tempo de execução | Deve instalá-los (ou usar peerDependenciesMeta para opcionais)  | **Apenas bibliotecas** |
| `peerDependenciesMeta` | Metadados para peerDependencies, usado para marcar peers como opcionais       | Nenhum - afeta apenas o comportamento do gerenciador de pacotes | **Apenas bibliotecas** |
| `devDependencies`      | Ferramentas usadas somente durante o desenvolvimento                          | Nenhum                                                          | Apps e bibliotecas     |

### Sobre peerDependenciesMeta

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

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

Isto é ú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 tempo de execução (React, ethers, @dcl/schemas)
* O consumidor (app) fornece essas dependências
* Previne instalações duplicadas e conflitos de singleton

**Apps / Serviços Finais:**

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

## 3. Quando Usar Cada Campo

> **Referência rápida**: Ver [Seção 4](#4-examples) para pacotes comuns e seu posicionamento recomendado.

### Usar peerDependencies para (Apenas Bibliotecas):

**Em bibliotecas/pacotes compartilhados**, usar `peerDependencies` para pacotes que devem resolver para uma única versão efetiva em tempo de execução:

* React, Redux, wagmi, ethers, viem
* @dcl/schemas e bibliotecas semelhantes de cruzamento de ecossistema
* decentraland/connect
* Drivers de BD ao compartilhar pools
* Qualquer biblioteca que dependa de singletons ou context

✅ Correto (Biblioteca):

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

❌ Incorreto (Biblioteca usando dependencies para libs compartilhadas):

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

### Usar dependencies para:

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

> **Importante**: Sempre usar **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, usar `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` estiver **obrigatório**: O consumidor deve instalá-lo ou o gerenciador de pacotes avisará
* `ethers` estiver **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 aumentam outras bibliotecas mas não são obrigatórios

### Usar devDependencies para:

* Ferramentas (TypeScript, ESLint, testadores, bundlers)

> **Importante**: Sempre usar **versões exatas/fixas** em `devDependencies` para garantir um ambiente de desenvolvimento consistente na 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 DEVERIAM 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-do-contribuidor/testing-standards.md)
* [Padrões de UI](https://github.com/decentraland/docs/blob/main/contributor/contributor-guides/ui-standards/README.md)
* [Padrões de Web UI](https://github.com/decentraland/docs/blob/main/contributor/contributor-guides/web-ui-standards/README.md)
* [Arquitetura WKC](https://github.com/decentraland/docs/blob/main/contributor/contributor-guides/well-known-components/README.md)
* [Diretrizes de Documentação de API](/contributor/contributor-pt/guias-do-contribuidor/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.decentraland.org/contributor/contributor-pt/guias-do-contribuidor/dependency-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.