pnpm allows to step directly into the installation process via special functions called hooks. Hooks can be declared in a file called pnpmfile.js.

By default, pnpmfile.js should be located in the same directory in which the lockfile is. So in a workspace with a shared lockfile, the pnpmfile.js should be in the root of the monorepo.

Hooks

tl;dr

Option Meaning
hooks.readPackage(pkg, context): pkg Allows to mutate every dependency's package.json
hooks.afterAllResolved(lockfile, context): lockfile Is called after resolution stage. Allows to mutate the lockfile object.

hooks.readPackage(pkg, context): pkg

Allows to mutate every dependency's package.json during resolution. These mutations are not saved to the filesystem but they can affect what gets installed.

An example of a pnpmfile.js that changes the dependencies field of a dependency: You will need to delete the pnpm-lock.yaml if you have already resolved the dependency you want change.

module.exports = {
  hooks: {
    readPackage
  }
}

function readPackage (pkg, context) {
  // Override the manifest of foo@1 after downloading it from the registry
  // Replace all dependencies with bar@2
  if (pkg.name === 'foo' && pkg.version.startsWith('1.')) {
    pkg.dependencies = {
      ...pkg.dependencies,
      bar: '^2.0.0'
    }
    context.log('bar@1 => bar@2 in dependencies of foo')
  }
  
  // This will fix any dependencies on baz to 1.2.3
  if (pkg.dependencies.baz === '*') {
    pkg.dependencies.baz = '1.2.3';
  }
  
  return pkg
}

Arguments

Usage

Substitute a package with your fork

Lets' suppose you forked a package with an important fix and you want the fixed version installed.

The following hook substitutes resolve with @zkochan's fork.

'use strict'
module.exports = {
  hooks: { readPackage }
}

function readPackage (pkg) {
  if (pkg.dependencies.resolve) {
    pkg.dependencies.resolve = 'zkochan/node-resolve'
  }

  return pkg
}
Packages validation

You want only packages with MIT license in your node_modules? Check the licenses and throw an exception if you don't like the package's license:

'use strict'
module.exports = {
  hooks: { readPackage }
}

function readPackage (pkg) {
  if (pkg.license !== 'MIT') {
    throw new Error('Invalid license!')
  }

  return pkg
}
Renaming bins

You want to rename a package's bin? Just replace it:

'use strict'
module.exports = {
  hooks: { readPackage }
}

function readPackage (pkg) {
  if (pkg.name === 'eslint') {
    pkg.bin = { jslint: pkg.bin }
  }

  return pkg
}

Now you can run jslint fix instead of eslint fix.

What you cannot do with readPackage

Removing the scripts field from the manifest of a dependency will not prevent pnpm from building that dependency. When building a dependency, pnpm reads the package.json of the package from the package's archive, which is not affected by the hook. In order to ignore a package's build, use the pnpm.neverBuiltDependencies field.

hooks.afterAllResolved(lockfile, context): lockfile

Added in: v1.41.0

Is called after resolution stage. Allows to mutate the lockfile object.

Arguments

Usage

module.exports = {
  hooks: { afterAllResolved }
}

function afterAllResolved (lockfile, context) {
  // ...
  return lockfile
}

Configs

ignore-pnpmfile

Added in: v1.25.0

pnpmfile.js will be ignored. Useful together with --ignore-scripts when you want to make sure that no script gets executed during install.

pnpmfile

Added in: v1.39.0

The location of the local pnpmfile.

global-pnpmfile

Added in: v1.39.0

The location of a global pnpmfile. A global pnpmfile is used by all projects during installation.

NOTE: It is recommended to use local pnpmfiles. Only use a global pnpmfile, if you use pnpm on projects that don't use pnpm as the primary package manager.