Skip to main content
Version: 4.x

pnpmfile.js

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#

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

hooks.readPackage(pkg, context): pkg#

Allows to mutate every dependency's package.json. 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 [email protected] after downloading it from the registry
// Replace all dependencies with [email protected]
if (pkg.name === 'foo' && pkg.version.startsWith('1.')) {
pkg.dependencies = {
bar: '^2.0.0'
}
context.log('[email protected] => [email protected] 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#

  • pkg - Manifest - The manifest of the package. Either the response from the registry or the package.json content.
  • context.log(msg) - Function - Allows to log messages.

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.

hooks.afterAllResolved(lockfile, context): lockfile#

Added in: v1.41.0

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

Arguments#

  • lockfile - object - The object that is saved to pnpm-lock.yaml.
  • context.log(msg) - Function - Allows to log messages.

Usage#

module.exports = {
hooks: { afterAllResolved }
}
function afterAllResolved (lockfile, context) {
// ...
return lockfile
}

Configs#

ignore-pnpmfile#

Added in: v1.25.0

  • Default: false
  • Type: Boolean

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

  • Default: pnpmfile.js
  • Type: path
  • Example: .pnpm/pnpmfile.js

The location of the local pnpmfile.

global-pnpmfile#

Added in: v1.39.0

  • Default: null
  • Type: path
  • Example: ~/.pnpm/global_pnpmfile.js

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.

Last updated on by Zoltan Kochan