La estructura de pnpm-lock.yaml

Casi nadie lee su pnpm-lock.yaml: lo tratan como un blob generado que ensucia los diffs. Es un error. El lockfile es un documento legible y muy bien diseñado, y saber recorrerlo te da un superpoder: entender por qué una versión concreta acabó en tu árbol, auditar un cambio sospechoso en un pull request, o diagnosticar un conflicto de peerDependencies sin adivinar. En 2026, con pnpm 10 y el formato de lockfile 9.0, la estructura es más limpia que nunca. Vamos a diseccionarla.

El encabezado: versión y settings

Las primeras líneas fijan el contrato de formato y las opciones que afectan a la resolución:

lockfileVersion: '9.0'

settings:
  autoInstallPeers: true
  excludeLinksFromLockfile: false

lockfileVersion es crítico: pnpm rechaza (o migra) lockfiles cuyo formato no entiende, y por eso todo el equipo debe usar versiones compatibles de pnpm —se fija con packageManager en package.json y Corepack—. El bloque settings graba las opciones que cambian el árbol resuelto. Se guardan aquí a propósito: si dependieran solo de tu configuración local, dos personas con distinto .npmrc obtendrían árboles distintos, y adiós reproducibilidad.

Los ajustes que verás con más frecuencia:

• autoInstallPeers — si pnpm instala automáticamente los peerDependencies no satisfechos.
• excludeLinksFromLockfile — si los enlaces locales se omiten del lockfile.
• peersSuffixMaxLength — cuánto se abrevia el identificador de peers en las claves (lo veremos abajo).

importers: el mapa de tus proyectos

Aquí es donde el diseño de pnpm brilla frente a otros lockfiles. La sección importers lista cada proyecto del workspace (cada package.json) por su ruta relativa, con sus dependencias declaradas y a qué versión exacta resolvió cada una:

importers:
  .:
    dependencies:
      zod:
        specifier: ^3.23.0
        version: 3.23.8
  packages/ui:
    dependencies:
      react:
        specifier: ^19.0.0
        version: 19.1.0

Cada entrada tiene el par clave: specifier (el rango que escribiste) y version (lo que se resolvió). Esa dualidad es el corazón del lockfile: cuando corres una instalación congelada (nivel 6.3), pnpm compara el specifier del lockfile con el rango de tu package.json; si no coinciden, aborta. En un repo de un solo paquete solo verás el importador .; en un monorepo verás uno por cada workspace, lo que convierte a importers en un índice navegable de todo el repo.

packages y snapshots: metadatos frente a grafo

El formato 9.0 separó en dos secciones lo que antes iba mezclado, y entender la división es la clave para leerlo:

packages:
  zod@3.23.8:
    resolution: {integrity: sha512-Aek05...MJVR7A==}
    engines: {node: '>=18'}

snapshots:
  zod@3.23.8: {}
  '@tanstack/react-query@5.59.0(react@19.1.0)':
    dependencies:
      '@tanstack/query-core': 5.59.0
      react: 19.1.0

Fíjate en la clave @tanstack/react-query@5.59.0(react@19.1.0): ese sufijo entre paréntesis es un peer identifier. Codifica que esta instancia de react-query se resolvió contra react@19.1.0. Si otro rincón del árbol necesitara react-query contra otra versión de React, aparecería una segunda entrada con distinto sufijo. Así pnpm representa, sin ambigüedad, que “el mismo paquete” puede tener grafos distintos según su contexto de peers. La razón de separar packages de snapshots es evitar duplicar los metadatos: la ficha de una versión se escribe una vez, y sus múltiples instanciaciones por contexto de peer viven baratas en snapshots.

resolution e integrity: identidad y verificación

Dentro de packages, el campo resolution responde a “de dónde sale esto y cómo sé que no ha sido alterado”:

  # desde el registro npm: hash de contenido
  esbuild@0.24.0:
    resolution: {integrity: sha512-vF1...Q==}

  # desde un tarball directo
  mi-lib@1.0.0:
    resolution: {tarball: https://ejemplo.dev/mi-lib-1.0.0.tgz}

El integrity es un hash Subresource Integrity del contenido del paquete. En la instalación, pnpm descarga (o toma del store global de contenido direccionable), recalcula el hash y lo compara: si difiere, falla en vez de instalar algo alterado. Rastrear un paquete es, entonces, mecánico:

• Búscalo en importers para ver quién lo pide directo y con qué rango.
• Búscalo en snapshots para ver quién lo arrastra transitivamente y bajo qué contexto de peers.
• Búscalo en packages para ver su procedencia e integridad.

Si usas catalogs (versiones compartidas de todo el workspace), el lockfile añade además una sección catalogs que graba a qué versión exacta resolvió cada entrada del catálogo: la misma lógica de specifier frente a version, pero elevada al conjunto del monorepo en un único punto de verdad.

flowchart TD
A[lockfileVersion y settings] --> B[importers: tus proyectos]
B --> C[specifier + version por dependencia]
C --> D[snapshots: el grafo resuelto]
D --> E[packages: ficha de cada version]
E --> F[resolution + integrity]
style B fill:#89b4fa,color:#11111b
style D fill:#cba6f7,color:#11111b
style E fill:#a6e3a1,color:#11111b