¿Qué es pnpm? Guía de uso

En el ámbito del desarrollo frontend, los gestores de paquetes son herramientas con las que interactuamos a diario. Desde el primer npm, pasando por yarn, hasta el actual **pnpm**, aclamado como el "más avanzado", la evolución de las herramientas siempre ha girado en torno a tres métricas clave: **velocidad, eficiencia espacial y seguridad de las dependencias**.

Este artículo te presentará pnpm y te enseñará cómo usarlo.

## ¿Qué es pnpm?

**pnpm** (Performant npm) es un gestor de paquetes extremadamente rápido y que ahorra espacio en disco.

### Ventajas clave

- **Velocidad Extrema (Performance):** pnpm es mucho más rápido que npm y yarn (generalmente más de 2 veces más rápido). Esto se debe a su mecanismo de instalación único, que evita la copia duplicada de una gran cantidad de archivos.
- **Ahorro de Espacio (Efficiency):** Esta es la característica estrella de pnpm. Utiliza **almacenamiento direccionable por contenido (Content-addressable storage)**. Si tienes 10 proyectos que usan la misma versión de `lodash`, solo se almacenará una vez en el disco.
- **Solución Perfecta para las "Dependencias Fantasma" (Safety):** npm/yarn tradicionales "aplanan" las dependencias (flat), lo que te permite acceder a paquetes en tu código que no has declarado en `package.json`. pnpm utiliza **enlaces simbólicos (Symlinks)** para construir un árbol de dependencias estricto, donde solo se puede acceder a los paquetes que has declarado.

## La "Forma Correcta" de Usar pnpm

### Instalar pnpm

Si ya tienes Node.js instalado, se recomienda instalarlo directamente a través de la herramienta de gestión principal:

```Bash
corepack enable
corepack prepare pnpm@latest --activate
```

O instálalo globalmente usando npm: `npm install -g pnpm`

### Tabla de Comandos Comunes

| **Operación**                 | **Comando npm**          | **Comando pnpm**                  |
| ----------------------------- | ------------------------ | --------------------------------- |
| Instalar dependencias         | `npm install`            | `pnpm install` (o `pnpm i`)     |
| Añadir paquete                | `npm install <pkg>`      | `pnpm add <pkg>`                  |
| Añadir dependencia de desarrollo | `npm i <pkg> -D`         | `pnpm add <pkg> -D`               |
| Eliminar paquete             | `npm uninstall <pkg>`    | `pnpm remove <pkg>`               |
| Ejecutar script               | `npm run <script>`       | `pnpm <script>` (sin `run`)     |
| Instalación global            | `npm install -g`         | `pnpm add -g`                     |

### Gestionar Versiones de Node

pnpm tiene una función de gestión de versiones incorporada, por lo que ni siquiera necesitas instalar nvm:

- Instalar una versión específica: `pnpm env use --global 20`

## Avanzado

### Configurar la Ruta de Almacenamiento (Store Path)

La lógica central de pnpm es almacenar todos los paquetes en un `store` global y luego mapearlos a los `node_modules` de cada proyecto a través de enlaces duros.

Por defecto, el store se ubicará en el directorio raíz de la unidad actual. Si deseas personalizar la ubicación de almacenamiento (por ejemplo, si te preocupa el espacio en el disco C:):

```Bash
# Ver la ruta actual del store
pnpm store path

# Establecer una ruta personalizada
pnpm config set store-dir D:\.pnpm-store
```

### Mejores Prácticas para Monorepo

pnpm es actualmente la mejor opción para gestionar **Monorepos** (proyectos con múltiples paquetes). Solo necesitas crear un archivo `pnpm-workspace.yaml` en el directorio raíz:

```yaml
packages:
  - 'packages/*'
  - 'apps/*'
```

Luego puedes instalar dependencias entre proyectos: `pnpm add lodash --filter @my-app/web`.

### Diferencias con npm/yarn

- **npm/yarn (v1):** Adoptan una estructura plana, lo que facilita los conflictos de dependencias y ocupa mucho espacio en disco.
- **yarn (v2/v3) Berry:** Introdujo el modo PnP, que es rápido pero presenta mayores desafíos de compatibilidad.
- **pnpm:** Ha encontrado el equilibrio. Mantiene la estructura física de `node_modules` (a través de enlaces simbólicos y duros), garantizando una alta compatibilidad, y al mismo tiempo logra un rendimiento extremo.

## Migrar Proyectos Antiguos a pnpm

Realiza las siguientes operaciones en el directorio raíz de tu proyecto:

1. **Instalar pnpm** (si aún no lo has hecho):

   ```Bash
   npm install -g pnpm
   ```

2. **Generar archivo de bloqueo de pnpm**: Ejecuta el siguiente comando; leerá automáticamente tu `package-lock.json` o `yarn.lock` existente y generará `pnpm-lock.yaml` sin descargar los paquetes.

   ```Bash
   pnpm import
   ```

3. **Eliminar archivos antiguos**: Para mantener el proyecto limpio, elimina los antiguos `node_modules` y los archivos de bloqueo antiguos.

   ```Bash
   # Los usuarios de Windows pueden usar el comando del o eliminar manualmente
   rm -rf node_modules package-lock.json yarn.lock
   ```

4. **Reinstalar dependencias**: Usa pnpm para completar el último paso:

   ```Bash
   pnpm install
   ```