Package manager

Package Manager — Reglas y Convenciones

---

1. Filosofía

1. pnpm por defecto — Es más rápido, eficiente en disco y estricto con dependencias. Node.js 22+ incluye Corepack, no hay excusa para no usarlo.
2. Lockfile obligatorio — pnpm-lock.yaml (o package-lock.json) se commitea siempre. Garantiza instalaciones reproducibles.
3. Frozen lockfile en CI — pnpm install --frozen-lockfile (o npm ci) falla si el lockfile no coincide con package.json. Nunca npm install en CI.
4. Corepack — Usar packageManager en package.json para fijar la versión exacta del package manager. Evita sorpresas entre entornos.
5. Un solo package manager por proyecto — No mezclar lockfiles. Si el proyecto usa pnpm, no committear package-lock.json.

---

2. Versiones Mínimas

Tecnología	Versión Mínima
Node.js	22+
pnpm	9+
npm	10+
Corepack	incluido en Node 22+

---

3. Instalación y Configuración Inicial

Corepack (recomendado)

Corepack viene incluido con Node.js 22+. Actívalo y úsalo para fijar el package manager del proyecto.

# Habilitar Corepack
corepack enable

# Fijar pnpm como package manager del proyecto
corepack use pnpm@latest

# O especificar versión exacta en package.json manualmente

package.json

{
  "name": "mi-proyecto",
  "version": "1.0.0",
  "packageManager": "[email protected]+sha256.a7b4c6d9f1e2b3c4d5e6f7a8b9c0d1e2f3a4b5c6",
  "engines": {
    "node": ">=22",
    "pnpm": ">=9"
  }
}

Inicializar proyecto nuevo

# Con pnpm
pnpm init

# Con npm
npm init

# Con Corepack auto-pin
export COREPACK_ENABLE_AUTO_PIN=1
pnpm init  # Agrega packageManager automáticamente

Aliases útiles

# .zshrc / .bashrc
alias p="pnpm"
alias px="pnpm dlx"
alias pi="pnpm install"
alias pa="pnpm add"
alias pad="pnpm add -D"
alias pu="pnpm update"
alias pr="pnpm remove"
alias pwhy="pnpm why"

---

4. pnpm (por defecto)

Instalar dependencias

pnpm install                          # Instalar todo
pnpm install --frozen-lockfile        # CI: falla si lockfile desactualizado
pnpm install --offline                # Solo desde cache local
pnpm fetch                            # Poblar store solo con el lockfile (rápido para CI)

Agregar dependencias

pnpm add react                        # Producción
pnpm add -D typescript                # Dev
pnpm add -O sax                       # Opcional
pnpm add eslint@9                     # Versión específica
pnpm add react@">=18 <19"             # Rango
pnpm add lodash-es --save-exact       # Versión exacta (sin ^)

Remover y actualizar

pnpm remove lodash
pnpm update                           # Minor/patch según rango
pnpm up -L                            # --latest: actualizar a última versión
pnpm up -r --workspace react          # Actualizar en todos los workspaces

Ejecutar scripts y comandos

pnpm dev                              # Ejecuta script "dev"
pnpm run test -- --coverage           # Pasar args al script
pnpm exec eslint .                    # Ejecutar binario desde node_modules
pnpm dlx create-vite                  # Ejecutar sin instalar (como npx)
pnpm why react                        # Por qué está instalado
pnpm list                             # Árbol de dependencias
pnpm licenses list                    # Listar licencias de paquetes
pnpm licenses list --long             # Con link al repo
pnpm audit                            # Auditoría de seguridad

Mantenimiento

pnpm store path                       # Ruta del store global
pnpm store status                     # Verificar integridad
pnpm store prune                      # Limpiar paquetes no referenciados
pnpm pm clean                         # Eliminar node_modules (built-in)
pnpm import                           # Generar pnpm-lock.yaml desde package-lock.json
pnpm patch react                      # Modificar dependencia directamente
pnpm dedupe                           # Deduplicar dependencias
pnpm outdated                         # Ver paquetes desactualizados

Configuración (.npmrc)

; .npmrc (aplica a pnpm y npm)

; Registry
registry=https://registry.npmjs.org/

; Comportamiento
auto-install-peers=true
strict-peer-dependencies=false
resolution-mode=highest              ; lowest-direct para máxima compatibilidad
node-linker=isolated                  ; hoisted | isolated | pnp
shamefully-hoist=true                 ; Hoistear para compatibilidad (evitar si es posible)

; Store
store-dir=~/.local/share/pnpm/store

; Seguridad
ignore-scripts=false
script-shell=/bin/bash

pnpmfile.ts (hooks)

// pnpmfile.ts — en la raíz del proyecto
export const hooks = {
  updateConfig(config) {
    return Object.assign(config, {
      enablePrePostScripts: false,
      resolutionMode: "highest",
      verifyDepsBeforeRun: "install",
    });
  },
};

---

5. npm (alternativa)

Instalar dependencias (npm)

npm install                           # Instalar todo
npm ci                                # CI: clean install desde lockfile (falla si desactualizado)
npm install --prefer-offline          # Usar cache cuando sea posible

Agregar dependencias (npm)

npm install react                     # Producción
npm install -D typescript             # Dev
npm install -O sax                    # Opcional
npm install eslint@9                  # Versión específica
npm install react@"^18"               # Rango
npm install --save-exact lodash-es    # Versión exacta

Remover y actualizar (npm)

npm uninstall lodash
npm update                            # Minor/patch según rango
npm outdated                          # Ver desactualizados

Ejecutar scripts y comandos (npm)

npm run dev
npm run test -- --coverage            # Pasar args
npm exec eslint .                     # Ejecutar binario local
npx create-vite                       # Ejecutar sin instalar
npm ls react                          # Árbol de dependencias
npm audit                             # Auditoría
npm audit fix                         # Auto-corregir vulnerabilidades
npm query ":outdated"                 # Consulta avanzada (JSON)
npm query ":deprecated"               # Paquetes deprecados
npm explain react                     # Por qué está instalado

npm Workspaces

npm init -w ./packages/a              # Crear nuevo workspace
npm install -w @mi-app/server         # Instalar en workspace específico
npm run test --workspaces             # Ejecutar en todos los workspaces
npm run test --workspace=@mi-app/app  # Ejecutar en uno específico
npm exec --ws -- eslint .             # Ejecutar en todos

Configuración (.npmrc) (npm)

; .npmrc
registry=https://registry.npmjs.org/
engine-strict=true
audit-level=high

---

6. package.json

Campos esenciales

{
  "name": "@mi-app/app",
  "version": "1.0.0",
  "private": true,
  "description": "Descripción del proyecto",
  "type": "module",
  "packageManager": "[email protected]",
  "engines": {
    "node": ">=22",
    "pnpm": ">=9"
  },
  "devEngines": {
    "node": ">=22",
    "pnpm": ">=9"
  },
  "scripts": {
    "preinstall": "npx only-allow pnpm",
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint .",
    "test": "vitest run",
    "preview": "vite preview"
  },
  "exports": {
    ".": "./src/index.js",
    "./utils": "./src/utils.js"
  },
  "dependencies": {
    "react": "catalog:"
  }
}

type: "module"

// package.json
{
  "type": "module"
}

Habilita ESM por defecto. Todos los .js se tratan como módulos ES. Para archivos CommonJS, usar extensión .cjs.

overrides / resolutions

{
  "pnpm": {
    "overrides": {
      "react": "^18.3.1",
      "react-dom@18": {
        "react": "^18.3.1"
      }
    }
  },
  "overrides": {
    "react": "^18.3.1"
  },
  "resolutions": {}
}

pnpm soporta pnpm.overrides en package.json y overrides en pnpm-workspace.yaml.

exports map

{
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./utils": {
      "import": "./dist/utils.js",
      "require": "./dist/utils.cjs"
    },
    "./package.json": "./package.json"
  }
}

---

7. Scripts

Pre/Post hooks

pnpm preinstall       # Corre automáticamente antes de pnpm install
pnpm postinstall      # Corre después de pnpm install
pnpm prepare          # Corre antes de publish y después de install

{
  "scripts": {
    "preinstall": "npx only-allow pnpm",
    "postinstall": "husky",
    "prepare": "husky",
    "dev": "vite",
    "build": "vite build",
    "test": "vitest run"
  }
}

enablePrePostScripts

# .npmrc
enablePrePostScripts=true  # pnpm: ejecuta pre/post automáticamente

Con enablePrePostScripts=true, pnpm dev ejecuta predev → dev → postdev.

Pasar argumentos a scripts

pnpm run test -- --coverage     # → vitest run --coverage
npm run test -- --coverage      # → vitest run --coverage
pnpm run lint -- --fix          # → eslint . --fix
pnpm dev -- --port 4000         # → vite --port 4000

only-allow pnpm

{
  "scripts": {
    "preinstall": "npx only-allow pnpm"
  }
}

Bloquea npm install o yarn en este proyecto. El script falla si se usa otro package manager.

---

8. Workspaces y Monorepos

pnpm Workspaces

# pnpm-workspace.yaml
packages:
  - "packages/*"
  - "apps/*"
  - "!**/test/**"

pnpm install                          # Instala todo el workspace
pnpm --filter @mi-app/server add express
pnpm -r build                         # Build en todos los paquetes
pnpm -r --parallel build              # Build paralelo

Filtering (pnpm)

pnpm --filter @mi-app/app test                                # Paquete específico
pnpm --filter "@mi-app/*" test                                # Por patrón
pnpm --filter "{packages/*}" test                             # Por glob
pnpm --filter ...@mi-app/app test                             # + dependientes
pnpm --filter @mi-app/app... test                             # + dependencias
pnpm --filter "@mi-app/*{components/**}[origin/main]" test    # Paquetes modificados

npm Workspaces (npm)

{
  "workspaces": ["packages/*", "apps/*"]
}

npm install -w @mi-app/server express    # Instalar en workspace
npm run test --workspaces                 # Todos los workspaces
npm run test --workspace=@mi-app/app      # Workspace específico
npm exec --ws -- eslint .                 # Ejecutar en todos

---

9. pnpm Catalogs

Catalog por defecto

# pnpm-workspace.yaml
packages:
  - "packages/*"

catalog:
  react: ^18.3.1
  react-dom: ^18.3.1
  typescript: ^5.5.0

{
  "dependencies": {
    "react": "catalog:",
    "react-dom": "catalog:"
  },
  "devDependencies": {
    "typescript": "catalog:"
  }
}

Named catalogs (para migraciones)

# pnpm-workspace.yaml
catalog:
  react: ^16.14.0
  react-dom: ^16.14.0

catalogs:
  react17:
    react: ^17.0.2
    react-dom: ^17.0.2
  react18:
    react: ^18.2.0
    react-dom: ^18.2.0

{
  "dependencies": {
    "react": "catalog:react18",
    "react-dom": "catalog:react18"
  }
}

Catalogs con overrides

# pnpm-workspace.yaml
catalog:
  react: ^18.3.1

overrides:
  react: "catalog:"

---

10. Seguridad

Auditoría

# pnpm
pnpm audit                            # Auditoría completa
pnpm audit --audit-level high         # Solo high/critical

# npm
npm audit                             # Auditoría
npm audit fix                         # Auto-corregir
npm audit fix --force                 # Forzar (major updates)

Overrides para vulnerabilidades

{
  "pnpm": {
    "overrides": {
      "semver@<7.5.2": ">=7.5.2",
      "braces@<3.0.3": ">=3.0.3"
    }
  }
}

supportedArchitectures

# pnpm-workspace.yaml
supportedArchitectures:
  os:
    - darwin
    - linux
  cpu:
    - x64
    - arm64

Buenas prácticas

• ignore-scripts=false — no desactivar scripts de instalación globalmente
• only-allow pnpm — prevenir instalación con npm/yarn
• Dependabot / Renovate — activar para PRs automáticos de seguridad
• pnpm audit en CI — fallar si hay vulnerabilidades high+
• Revisar npm fund para entender qué proyectos se financian

---

11. Publicación

# pnpm
pnpm publish                          # Publicar paquete
pnpm publish --access public          # Paquetes scoped (@mi-app/)
pnpm publish --publish-branch main    # Rama desde la que publicar
pnpm -r publish                       # Publicar todo el workspace

# npm
npm publish                           # Publicar
npm publish --access public           # Paquete scoped
npm publish --provenance              # Publicar con provenance (GitHub Actions)

Cambiosets (monorepos)

pnpm add -DW @changesets/cli
pnpm changeset init
pnpm changeset                        # Crear nuevo changeset
pnpm changeset version                # Bump versiones
pnpm changeset publish                # Publicar

package.json para publicación

{
  "name": "@mi-app/utils",
  "version": "1.0.0",
  "private": false,
  "publishConfig": {
    "access": "public"
  },
  "files": ["dist", "!dist/**/*.test.*"],
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  },
  "sideEffects": false
}

---

12. Actualizaciones

pnpm

pnpm up                              # Actualizar según rangos
pnpm up -L                           # --latest: última versión
pnpm up -r --workspace react         # Workspace específico
pnpm outdated                        # Ver desactualizados

npm-check-updates

pnpm dlx npm-check-updates           # Ver actualizaciones disponibles
pnpm dlx npm-check-updates -u        # Actualizar package.json
pnpm dlx ncu                         # Aliases más corto

Renovate / Dependabot

# .github/renovate.json
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "packageRules":
    [
      { "matchUpdateTypes": ["patch"], "automerge": true },
      {
        "matchPackageNames": ["react", "react-dom"],
        "schedule": ["before 8am on monday"],
      },
    ],
}

---

13. Cache y Disco

pnpm Store

pnpm store path                       # Mostrar ruta del store
pnpm store status                     # Verificar integridad
pnpm store prune                      # Limpiar paquetes no usados
pnpm store add express@4              # Agregar específico al store

Content-addressable storage

pnpm usa un store global con content-addressable storage. Un mismo archivo se almacena una sola vez, referenciado por su hash. Esto ahorra espacio cuando múltiples proyectos usan las mismas versiones.

Cache en CI

# GitHub Actions cache
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: "pnpm"

- name: Install dependencies
  run: pnpm install --frozen-lockfile

pnpm fetch en CI

# Paso rápido: solo llenar store desde lockfile (sin node_modules)
- run: pnpm fetch
# Luego instalar desde store (mucho más rápido)
- run: pnpm install --offline

---

14. CI/CD

Pipeline básico

name: CI
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: "pnpm"

      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build

Pipeline optimizado con pnpm fetch

jobs:
  install:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: "pnpm"

      - run: pnpm fetch # Llena store desde lockfile
      - run: pnpm install --offline # Instala desde store
      - run: pnpm lint
      - run: pnpm test
      - run: pnpm build

npm CI

- run: npm ci
- run: npm run build

---

15. Migración entre package managers

De npm a pnpm

pnpm import                           # Genera pnpm-lock.yaml desde package-lock.json
rm -rf node_modules package-lock.json
pnpm install

De yarn a pnpm

pnpm import                           # Soporta yarn.lock
rm -rf node_modules yarn.lock
pnpm install

Lockfile drift

pnpm install --frozen-lockfile        # Fallará si package.json no coincide con lockfile
pnpm install --lockfile-only          # Solo actualizar lockfile sin node_modules

---

16. Troubleshooting

Problemas comunes

# Error: "Cannot find module" después de agregar dependencia
pnpm install                          # Reinstalar

# Error: Lockfile desactualizado en CI
pnpm install --no-frozen-lockfile     # Actualizar (local)
git add pnpm-lock.yaml                # Commitear el lockfile actualizado

# Error: Versión incorrecta de pnpm
corepack use pnpm@latest              # Actualizar
pnpm env use --global 22              # pnpm: cambiar versión de Node

# Error: EACCES en global installs
# Usar Corepack o configurar prefix en .npmrc
npm config set prefix ~/.local

# Error: conflictos de peer dependencies
# pnpm: strict-peer-dependencies=false en .npmrc
# npm:  npm install --legacy-peer-deps

---

17. Prohibiciones

• ❌ NO committear node_modules/ en ningún caso
• ❌ NO mezclar lockfiles (pnpm-lock.yaml + package-lock.json en el mismo proyecto)
• ❌ NO usar npm install si el proyecto está configurado con pnpm
• ❌ NO usar npm install en CI (usar npm ci o pnpm install --frozen-lockfile)
• ❌ NO usar --force o --legacy-peer-deps como solución permanente
• ❌ NO dejar versiones sueltas sin rango ("react": "18.3.1" sin ^ explícito si se permite patch)
• ❌ NO desactivar ignore-scripts globalmente (solo por paquete si es necesario)
• ❌ NO ignorar vulnerabilidades (pnpm audit / npm audit debe pasar en CI)
• ❌ NO publicar paquetes sin build previa
• ❌ NO borrar pnpm-lock.yaml / package-lock.json para "solucionar" problemas
• ❌ NO instalar dependencias globales sin --global explícito
• ❌ NO usar npm link en proyectos que usan pnpm (usar pnpm link)
• ❌ NO modificar node_modules manualmente

---

18. Referencias

Nota: Para CI/CD y build scripts, ver Deploy Nota: Para scripts en package.json, ver JavaScript Nota: Para control de versiones, ver Git

Última actualización: 2026-07