Store & Lockfile Settings

Store Settings

storeDir

• Padrão:
  • If the $PNPM_HOME env variable is set, then $PNPM_HOME/store
  • If the $XDG_DATA_HOME env variable is set, then $XDG_DATA_HOME/pnpm/store
  • On Windows: ~/AppData/Local/pnpm/store
  • On macOS: ~/Library/pnpm/store
  • On Linux: ~/.local/share/pnpm/store
• Type: path

O local onde todos os pacotes são salvos no disco.

A store deve estar sempre no mesmo disco em que a instalação está acontecendo, para exista uma store por disco. Se houver um diretório home no disco atual, então a store será criado dentro dele. Se não houver algum diretório home no disco, a store será criada a partir da raiz do sistema de arquivos. For example, if installation is happening on a filesystem mounted at /mnt, then the store will be created at /mnt/.pnpm-store. O mesmo acontece para os sistemas windows.

É possível definir uma store a partir de um disco diferente, mas nesse caso o pnpm vai copiar os pacotes da store ao invés de fazer um hard-linking deles, pois hard links só são possíveis no mesmo sistema de arquivos.

important

The pnpm store is intended to be shared only between mutually trusted users, jobs, and processes. If you configure a shared storeDir, protect it with filesystem permissions so untrusted users cannot write to it. The store is part of pnpm's trust domain: packages may be hard linked from it, and the store index (index.db) records the hashes used to verify cached files.

verifyStoreIntegrity

• Default: true
• Type: Boolean

By default, if a file in the store has been modified, the content of this file is checked before linking it to a project's node_modules. If verifyStoreIntegrity is set to false, files in the content-addressable store will not be checked during installation.

This setting helps detect accidental store corruption. It does not make a store that is writable by untrusted users safe, because an attacker who can write to the store can alter both cached package contents and the metadata used to verify them.

useRunningStoreServer

perigo

Deprecated feature

• Default: false
• Type: Boolean

Só permite a instalação com um servidor de armazenamento. Se nenhum servidor de armazenamento estiver em execução, a instalação falhará.

strictStorePkgContentCheck

• Default: true
• Type: Boolean

Some registries allow the exact same content to be published under different package names and/or versions. This breaks the validity checks of packages in the store. To avoid errors when verifying the names and versions of such packages in the store, you may set the strictStorePkgContentCheck setting to false.

frozenStore

Added in: v11.7.0

• Default: false
• Type: Boolean

Lets pnpm install run against a package store that lives on a read-only filesystem — for example a Nix store, a read-only bind mount, or an OCI image layer. When enabled, pnpm opens the store's SQLite index.db in immutable mode (bypassing the WAL/-shm sidecar files that otherwise can't be created on a read-only directory) and suppresses every code path that would write to the store.

Pair it with --offline and --frozen-lockfile against a fully-populated store:

pnpm install --frozen-store --offline --frozen-lockfile

The store must already contain everything the install needs, including the build output of any package whose lifecycle scripts are approved (or that has a patch applied). Under the global virtual store, those package directories live inside the store, so if a required build is missing the install fails up front with ERR_PNPM_FROZEN_STORE_NEEDS_BUILD — seed the store with those builds first. If the store is missing its content directory entirely, the install fails fast with ERR_PNPM_FROZEN_STORE_INCOMPLETE rather than trying to initialize it.

frozenStore is incompatible with --force and with a configured pnpr server, since both write into the store. The side effects cache is not written either.

nota

The read-only store open requires Node.js >=22.15.0, >=23.11.0, or >=24.0.0. On older runtimes, --frozen-store fails with ERR_PNPM_FROZEN_STORE_UNSUPPORTED_NODE.

Configurações do arquivo de bloqueio

lockfile

• Default: true
• Type: Boolean

When set to false, pnpm won't read or generate a pnpm-lock.yaml file.

preferFrozenLockfile

• Default: true
• Type: Boolean

When set to true and the available pnpm-lock.yaml satisfies the package.json dependencies directive, a headless installation is performed. A headless installation skips all dependency resolution as it does not need to modify the lockfile.

lockfileIncludeTarballUrl

• Default: false
• Type: Boolean

Add the full URL to the package's tarball to every entry in pnpm-lock.yaml.

gitBranchLockfile

• Default: false
• Type: Boolean

When set to true, the generated lockfile name after installation will be named based on the current branch name to completely avoid merge conflicts. For example, if the current branch name is feature-foo, the corresponding lockfile name will be pnpm-lock.feature-foo.yaml instead of pnpm-lock.yaml. It is typically used in conjunction with the command line argument --merge-git-branch-lockfiles or by setting mergeGitBranchLockfilesBranchPattern in the pnpm-workspace.yaml file.

mergeGitBranchLockfilesBranchPattern

• Default: null
• Type: Array or null

This configuration matches the current branch name to determine whether to merge all git branch lockfile files. By default, you need to manually pass the --merge-git-branch-lockfiles command line parameter. This configuration allows this process to be automatically completed.

Por exemplo:

mergeGitBranchLockfilesBranchPattern:
- main
- release*

You may also exclude patterns using !.

peersSuffixMaxLength

• Default: 1000
• Type: number

Max length of the peer IDs suffix added to dependency keys in the lockfile. If the suffix is longer, it is replaced with a hash.