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.
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
}
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.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
}
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
}
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
.
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.
lockfile
- object - The object that is saved to pnpm-lock.yaml
.context.log(msg)
- Function - Allows to log messages.module.exports = {
hooks: { afterAllResolved }
}
function afterAllResolved (lockfile, context) {
// ...
return lockfile
}
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.
Added in: v1.39.0
The location of the local 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.