docs/pnpmfile.md
pnpm lets you hook directly into the installation process via special functions
(hooks). Hooks can be declared in a file called .pnpmfile.mjs (ESM) or .pnpmfile.cjs (CommonJS).
By default, .pnpmfile.mjs should be located in the same directory as the
lockfile. For instance, in a workspace with a shared lockfile,
.pnpmfile.mjs should be in the root of the monorepo.
| Hook Function | Process | Uses |
|---|---|---|
hooks.readPackage(pkg, context): pkg | Called after pnpm parses the dependency's package manifest | Allows you to mutate a dependency's package.json |
hooks.afterAllResolved(lockfile, context): lockfile | Called after the dependencies have been resolved. | Allows you to mutate the lockfile. |
hooks.beforePacking(pkg): pkg | Called before creating a tarball during pack/publish | Allows you to customize the published package.json |
hooks.readPackage(pkg, context): pkg | Promise<pkg>Allows you to mutate a dependency's package.json after parsing and prior to
resolution. These mutations are not saved to the filesystem, however, they will
affect what gets resolved in the lockfile and therefore what gets installed.
Note that you will need to delete the pnpm-lock.yaml if you have already
resolved the dependency you want to modify.
:::tip
If you need changes to package.json saved to the filesystem, you need to use the pnpm patch command and patch the package.json file.
This might be useful if you want to remove the bin field of a dependency for instance.
:::
pkg - The manifest of the package. Either the response from the registry or
the package.json content.context - Context object for the step. Method #log(msg) allows you to use
a debug log for the step.Example .pnpmfile.mjs (changes the dependencies of a dependency):
function readPackage(pkg, context) {
// Override the manifest of [email protected] after downloading it from the registry
if (pkg.name === 'foo' && pkg.version.startsWith('1.')) {
// Replace [email protected] with [email protected]
pkg.dependencies = {
...pkg.dependencies,
bar: '^2.0.0'
}
context.log('bar@1 => bar@2 in dependencies of foo')
}
// This will change any packages using [email protected] to use [email protected]
if (pkg.dependencies.baz) {
pkg.dependencies.baz = '1.2.3';
}
return pkg
}
export const hooks = {
readPackage
}
Removing the scripts field from a dependency's manifest via readPackage will
not prevent pnpm from building the 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
allowBuilds field.
hooks.updateConfig(config): config | Promise<config>Added in: v10.8.0
Allows you to modify the configuration settings used by pnpm. This hook is most useful when paired with configDependencies, allowing you to share and reuse settings across different Git repositories.
For example, @pnpm/plugin-better-defaults uses the updateConfig hook to apply a curated set of recommended settings.
export const hooks = {
updateConfig (config) {
return Object.assign(config, {
enablePrePostScripts: false,
optimisticRepeatInstall: true,
resolutionMode: 'lowest-direct',
verifyDepsBeforeRun: 'install',
})
}
}
hooks.afterAllResolved(lockfile, context): lockfile | Promise<lockfile>Allows you to mutate the lockfile output before it is serialized.
lockfile - The lockfile resolutions object that is serialized to
pnpm-lock.yaml.context - Context object for the step. Method #log(msg) allows you to use
a debug log for the step.function afterAllResolved(lockfile, context) {
// ...
return lockfile
}
export const hooks = {
afterAllResolved
}
There are none - anything that can be done with the lockfile can be modified via this function, and you can even extend the lockfile's functionality.
hooks.beforePacking(pkg): pkg | Promise<pkg>Added in: v10.28.0
Allows you to modify the package.json manifest before it is packed into a tarball during pnpm pack or pnpm publish. This is useful for customizing the published package without affecting your local development package.json.
Unlike hooks.readPackage, which modifies how dependencies are resolved during installation, beforePacking only affects the contents of the tarball that gets published.
pkg - The package manifest object that will be included in the published tarball.function beforePacking(pkg) {
// Remove development-only fields from published package
delete pkg.devDependencies
delete pkg.scripts.test
// Add publication metadata
pkg.publishedAt = new Date().toISOString()
// Modify package exports for production
if (pkg.name === 'my-package') {
pkg.main = './dist/index.js'
}
return pkg
}
export const hooks = {
beforePacking
}
:::note
The modifications made by this hook only affect the package.json inside the tarball. Your local package.json file remains unchanged.
:::
hooks.preResolution(options): Promise<void>This hook is executed after reading and parsing the lockfiles of the project, but before resolving dependencies. It allows modifications to the lockfile objects.
options.existsCurrentLockfile - A boolean that is true if the lockfile at node_modules/.pnpm/lock.yaml exists.options.currentLockfile - The lockfile object from node_modules/.pnpm/lock.yaml.options.existsNonEmptyWantedLockfile - A boolean that is true if the lockfile at pnpm-lock.yaml exists.options.wantedLockfile - The lockfile object from pnpm-lock.yaml.options.lockfileDir - The directory where the wanted lockfile is found.options.storeDir - The location of the store directory.options.registries - A map of scopes to registry URLs.hooks.importPackage(destinationDir, options): Promise<string | undefined>This hook allows to change how packages are written to node_modules. The return value is optional and states what method was used for importing the dependency, e.g.: clone, hardlink.
destinationDir - The destination directory where the package should be written.options.disableRelinkLocalDirDepsoptions.filesMapoptions.forceoptions.resolvedFromoptions.keepModulesDirAdded in: v10.16.0
Finder functions are used with pnpm list and pnpm why via the --find-by flag.
Example:
export const finders = {
react17: (ctx) => {
return ctx.readManifest().peerDependencies?.react === "^17.0.0"
}
}
Usage:
pnpm why --find-by=react17
See Finders for more details.
The pnpmfile will be ignored. Useful together with --ignore-scripts when you
want to make sure that no script gets executed during install.
The location of the local pnpmfile(s).
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.
:::