> 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-es/guias-para-colaboradores/dependency-management.md).

# Gestión de dependencias

Este documento define las prácticas recomendadas para gestionar dependencias en proyectos JavaScript/TypeScript en todo el ecosistema de Decentraland. Se aplica a front-end, back-end, SDKs, bibliotecas compartidas y cualquier paquete basado en npm/yarn/pnpm.

> **TL;DR**:
>
> * **Estrategia de versiones** → Usar **versiones exactas/fijas** para `dependencias` (seguridad) y `devDependencies` (entorno de desarrollo consistente). Usar **rangos de versión** solo para `peerDependencies` (flexibilidad).
> * **Excepción** → Los paquetes de Decentraland (`@dcl/*`, `decentraland-*`) pueden usar rangos de versión (`^`) ya que son paquetes internos de confianza.
> * **Bibliotecas/paquetes compartidos** → Usar `peerDependencies` con rangos de versión (^) para bibliotecas compartidas (React, @dcl/schemas, etc.). Usar `dependencias` con versiones exactas solo para utilidades seguras de duplicar.
> * **Aplicaciones/servicios finales** → Usar `dependencias` con versiones exactas para paquetes de runtime (React, ethers, etc.).

## 1. Fundamento

Muchas bibliotecas dependen de singletons globales, React Context, identidad de clase, cachés compartidas, enums de schema o pools de DB compartidos. Instalar múltiples versiones de la misma biblioteca puede causar:

* Context no compartido entre copias
* Cachés o pools duplicados
* Comprobaciones instanceof fallidas
* Desajustes de enum/symbol
* Tamaño del bundle aumentado
* Bugs de runtime difíciles de diagnosticar

La gestión correcta de dependencias previene estos problemas.

### No objetivos

Esta norma no **no** intenta:

* Imponer un único gestor de paquetes (npm, yarn, pnpm son todos compatibles)
* Garantizar una única copia física en `node_modules` (el enfoque está en la deduplicación de runtime/bundle)

## 2. Definiciones

| Campo                  | Propósito                                                                 | Responsabilidad del consumidor                                     | Aplica a                   |
| ---------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------- |
| `dependencias`         | Paquetes usados internamente por el módulo                                | Ninguna: no se espera que el consumidor los proporcione            | Aplicaciones y bibliotecas |
| `peerDependencies`     | Paquetes que deben resolverse a una única versión efectiva en runtime     | Debe instalarlos (o usar peerDependenciesMeta para los opcionales) | **Solo bibliotecas**       |
| `peerDependenciesMeta` | Metadatos para peerDependencies, usados para marcar peers como opcionales | Ninguno: solo afecta el comportamiento del gestor de paquetes      | **Solo bibliotecas**       |
| `devDependencies`      | Herramientas usadas solo durante el desarrollo                            | Ninguno                                                            | Aplicaciones y bibliotecas |

### Acerca de peerDependenciesMeta

`peerDependenciesMeta` es un campo que proporciona metadatos sobre tus `peerDependencies`. El caso de uso más común es marcar peers como **opcionales**:

* **Peers requeridos** (predeterminado): El gestor de paquetes advertirá si no está instalado
* **Peers opcionales**: El gestor de paquetes no advertirá si falta; tu paquete debe manejar su ausencia con gracia

Esto es útil para paquetes que pueden funcionar con o sin ciertas dependencias (p. ej., una utilidad que funciona con o sin React, o una biblioteca que admite múltiples proveedores Web3).

### Apps vs Bibliotecas

**Bibliotecas / Paquetes compartidos:**

* Usa `peerDependencies` para paquetes que deben resolverse a una única versión efectiva en runtime (React, ethers, @dcl/schemas)
* El consumidor (app) proporciona estas dependencias
* Evita instalaciones duplicadas y conflictos de singleton

**Aplicaciones / Servicios finales:**

* A menudo usan `dependencias` para paquetes de runtime (React, ethers, etc.)
* Son el consumidor final, por lo que la duplicación no es una preocupación
* `peerDependencies` sigue siendo válido si la app puede ser consumida como dependencia

## 3. Cuándo usar cada campo

> **Referencia rápida**: Ver [Sección 4](#4-examples) para paquetes comunes y su ubicación recomendada.

### Usar peerDependencies para (solo bibliotecas):

**En bibliotecas/paquetes compartidos**, usar `peerDependencies` para paquetes que deben resolverse a una única versión efectiva en runtime:

* React, Redux, wagmi, ethers, viem
* @dcl/schemas y bibliotecas similares entre ecosistemas
* decentraland/connect
* controladores de base de datos cuando se comparten pools
* Cualquier biblioteca que dependa de singletons o Context

✅ Correcto (biblioteca):

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

❌ Incorrecto (biblioteca que usa dependencies para bibliotecas compartidas):

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

### Usar dependencies para:

* Utilidades seguras de duplicar (lodash-es, date-fns)
* **En aplicaciones**: Paquetes de runtime como React, ethers (cuando la app es el consumidor final)

> **Importante**: Usar siempre **versiones exactas/fijas** en `dependencias` por seguridad.

✅ Correcto (biblioteca):

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

✅ Correcto (App):

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

### peerDependencies opcionales (peerDependenciesMeta)

Para paquetes reutilizables que funcionan con o sin ciertas dependencias, usar `peerDependenciesMeta` para marcar peers como opcionales:

✅ Correcto:

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

**Qué significa esto:**

* `react` está **obligatorio**: El consumidor debe instalarlo o el gestor de paquetes advertirá
* `ethers` está **opcionales**: El consumidor no necesita instalarlo; tu paquete debe comprobar su presencia antes de usarlo

**Casos de uso:**

* Paquetes que funcionan tanto en entornos React como no React
* Bibliotecas que admiten múltiples proveedores Web3 (ethers, viem, etc.)
* Utilidades que mejoran otras bibliotecas pero no son requeridas

### Usar devDependencies para:

* Herramientas (TypeScript, ESLint, testers, bundlers)

> **Importante**: Usar siempre **versiones exactas/fijas** en `devDependencies` para garantizar un entorno de desarrollo coherente en todo el equipo.

✅ Correcto:

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

## 4. Ejemplos

### Paquetes que DEBEN ser peerDependencies (contexto compartido / 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`

### Paquetes que DEBERÍAN ser dependencies (seguros de duplicar)

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

## 5. Normas relacionadas

* [Estándares de prueba](/contributor/contributor-es/guias-para-colaboradores/testing-standards.md)
* [Estándares de UI](https://github.com/decentraland/docs/tree/main/contributor/contributor-guides/ui-standards/README.md)
* [Estándares de UI web](https://github.com/decentraland/docs/tree/main/contributor/contributor-guides/web-ui-standards/README.md)
* [Arquitectura WKC](https://github.com/decentraland/docs/tree/main/contributor/contributor-guides/well-known-components/README.md)
* [Pautas de documentación de API](/contributor/contributor-es/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-es/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.