メインコンテンツまでスキップ
Version: Next

.pnpmfile.mjs

pnpm を使用すると、特別な関数 (フック) を介してインストールプロセスを直接フックできます。 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.

フック​

概要​

フック関数タイミング使い方
hooks.readPackage(pkg, context): pkgpnpm が依存パッケージのマニフェストを解析した後に呼び出されますAllows you to mutate a dependency's package.json.
hooks.afterAllResolved(lockfile, context): lockfile依存関係が解決された後に呼び出されますロックファイルを変更できます
hooks.beforePacking(pkg): pkgCalled before creating a tarball during pack/publishAllows you to customize the published package.json
resolversCalled during package resolution.Allows you to register custom package resolvers.
fetchersCalled during package fetching.Allows you to register custom package fetchers.

hooks.readPackage(pkg, context): pkg | Promise<pkg>​

解析後、解決の前に、 package.json の依存関係の変換をすることができます。 これらの変更はファイルシステムに保存されませんが、ロックファイルで解決される内容、したがってインストールされる内容に影響を与えます。

既に変更を加えたい依存関係が解決されている場合は、pnpm-lock.yaml を削除する必要があることに注意してください。

ヒント

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. 例えば依存関係の bin フィールドを削除したい場合に便利かもしれません。

引数​

  • pkg - パッケージのマニフェスト。 レジストリのレスポンス、もしくは package.json の内容。
  • context - ステップのコンテキストオブジェクト。 #log(msg) メソッドでは、ステップに対してデバッグログを出力できます。

使い方​

Example .pnpmfile.mjs (changes the dependencies of a dependency):

function readPackage(pkg, context) {
  // レジストリからダウンロード後に foo@1.x のマニフェストを変更する
  if (pkg.name === 'foo' && pkg.version.startsWith('1.')) {
    // Replace bar@x.x.x with bar@2.0.0
    pkg.dependencies = {
      ...pkg.dependencies,
      bar: '^2.0.0'
    }
    context.log('bar@1 => bar@2 in dependencies of foo')
  }

  // This will change any packages using baz@x.x.x to use baz@1.2.3
  if (pkg.dependencies.baz) {
    pkg.dependencies.baz = '1.2.3';
  }

  return pkg
}

export const hooks = {
  readPackage
}

既知の制限事項​

readPackage にて依存パッケージのマニフェストから scripts フィールドを から削除しても、pnpm が依存のビルドを省略するようにはなりません。 依存パッケージをビルドする際に、 pnpm はパッケージのアーカイブから package.json を読み取ります。これはフックの影響を受けません。 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.

使用例​

.pnpmfile.mjs
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>​

シリアライズされる前にロックファイルの出力を変更できます。

引数​

  • lockfile - pnpm-lock.yaml にシリアライズされるロックファイル解決の情報を持つオブジェクト。
  • context - ステップのコンテキストオブジェクト。 #log(msg) メソッドでは、ステップに対してデバッグログを出力できます。

使用例​

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

export const hooks = {
  afterAllResolved
}

既知の制限事項​

何もありません - ロックファイルでできることは、この関数を介して変更することができます。 ロックファイルの機能を拡張することもできます。

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.

使用例​

.pnpmfile.mjs
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
}
メモ

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.disableRelinkLocalDirDeps
  • options.filesMap
  • options.force
  • options.resolvedFrom
  • options.keepModulesDir

hooks.fetchers​

Removed in v11.0.0

hooks.fetchers has been removed. Use top-level fetchers instead. See the Custom Fetchers section for the new API.

Finders​

Added in: v10.16.0

Finder functions are used with pnpm list and pnpm why via the --find-by flag.

例:

.pnpmfile.mjs
export const finders = {
  react17: (ctx) => {
    return ctx.readManifest().peerDependencies?.react === "^17.0.0"
  }
}

使い方

pnpm why --find-by=react17

See Finders for more details.

Custom Resolvers and Fetchers​

Added in: v11.0.0

Custom resolvers and fetchers allow you to implement custom package resolution and fetching logic for new package identifier schemes (like my-protocol:package-name). They are registered as top-level exports in .pnpmfile.cjs:

module.exports = {
  resolvers: [customResolver1, customResolver2],
  fetchers: [customFetcher1, customFetcher2],
}

TypeScript Interfaces​

interface CustomResolver {
  canResolve?: (wantedDependency: WantedDependency) => boolean | Promise<boolean>
  resolve?: (wantedDependency: WantedDependency, opts: ResolveOptions) => ResolveResult | Promise<ResolveResult>
  shouldRefreshResolution?: (depPath: string, pkgSnapshot: PackageSnapshot) => boolean | Promise<boolean>
}

interface CustomFetcher {
  canFetch?: (pkgId: string, resolution: Resolution) => boolean | Promise<boolean>
  fetch?: (cafs: Cafs, resolution: Resolution, opts: FetchOptions, fetchers: Fetchers) => FetchResult | Promise<FetchResult>
}

Custom Resolvers​

Custom resolvers convert package descriptors (e.g., foo@^1.0.0) into resolutions that are stored in the lockfile.

Resolver Interface​

A custom resolver is an object that can implement any combination of the following methods:

canResolve(wantedDependency): boolean | Promise<boolean>​

Determines whether this resolver can resolve a given wanted dependency.

Arguments:

  • wantedDependency - Object with:
    • alias - The package name or alias as it appears in package.json
    • bareSpecifier - The version range, git URL, file path, or other specifier

Returns: true if this resolver can handle the package, false otherwise. This determines whether resolve will be called.

resolve(wantedDependency, opts): ResolveResult | Promise<ResolveResult>​

Resolves a wanted dependency to specific package metadata and resolution information.

Arguments:

  • wantedDependency - The wanted dependency (same as canResolve)
  • opts - Object with:
    • lockfileDir - Directory containing the lockfile
    • projectDir - The project root directory
    • preferredVersions - Map of package names to preferred versions

Returns: Object with:

  • id - Unique package identifier (e.g., 'custom-pkg@1.0.0')
  • resolution - Resolution metadata. This can be:
    • Standard resolution, e.g. { tarball: 'https://...', integrity: '...' }
    • Custom resolution: { type: 'custom:cdn', url: '...' }

Custom resolutions must be handled by a corresponding custom fetcher.

Custom Resolution Types

Custom resolutions must use the custom: prefix in their type field (e.g., custom:cdn, custom:artifactory) to differentiate them from pnpm's built-in resolution types.

shouldRefreshResolution(depPath, pkgSnapshot): boolean | Promise<boolean>​

Return true to trigger full resolution of all packages, skipping the "Lockfile is up to date" optimization. This is useful for implementing time-based cache invalidation or other custom re-resolution logic.

Arguments:

  • depPath - The package identifier string (e.g., lodash@4.17.21)
  • pkgSnapshot - The lockfile entry for this package, providing direct access to the resolution, dependencies, etc.

Returns: true to force re-resolution, false otherwise.

メモ

shouldRefreshResolution is skipped during frozen lockfile installs, as no resolution is allowed in that mode.

Custom Fetchers​

Custom fetchers completely handle fetching for custom package types, downloading package contents from custom sources and storing them in pnpm's content-addressable file system.

Fetcher Interface​

A custom fetcher is an object that can implement the following methods:

canFetch(pkgId, resolution): boolean | Promise<boolean>​

Determines whether this fetcher can fetch a package with the given resolution.

Arguments:

  • pkgId - The unique package identifier from the resolution phase
  • resolution - The resolution object from a resolver's resolve method

Returns: true if this fetcher can handle fetching this package, false otherwise.

fetch(cafs, resolution, opts, fetchers): FetchResult | Promise<FetchResult>​

Fetches package files and returns metadata about the fetched package.

Arguments:

  • cafs - Content-addressable file system interface for storing files
  • resolution - The resolution object (same as passed to canFetch)
  • opts - Fetch options including:
    • lockfileDir - Directory containing the lockfile
    • filesIndexFile - Path for the files index
    • onStart - Optional callback when fetch starts
    • onProgress - Optional progress callback
  • fetchers - Object containing pnpm's standard fetchers for delegation:
    • remoteTarball - Fetcher for remote tarballs
    • localTarball - Fetcher for local tarballs
    • gitHostedTarball - Fetcher for GitHub/GitLab/Bitbucket tarballs
    • directory - Fetcher for local directories
    • git - Fetcher for git repositories

Returns: Object with:

  • filesIndex - Map of relative file paths to their physical locations. For remote packages, these are paths in pnpm's content-addressable store (CAFS). For local packages (when local: true), these are absolute paths to files on disk.
  • manifest - Optional. The package.json from the fetched package. If not provided, pnpm will read it from disk when needed. Providing it avoids an extra file I/O operation and is recommended when you have the manifest data readily available (e.g., already parsed during fetch).
  • requiresBuild - Boolean indicating whether the package has build scripts that need to be executed. Set to true if the package has preinstall, install, or postinstall scripts, or contains binding.gyp or .hooks/ files. Standard fetchers determine this automatically using the manifest and file list.
  • local - Optional. Set to true to load the package directly from disk without copying to pnpm's store. When true, filesIndex should contain absolute paths to files on disk, and pnpm will hardlink them to node_modules instead of copying. This is how the directory fetcher handles local dependencies (e.g., file:../my-package).
Delegating to Standard Fetchers

Custom fetchers can delegate to pnpm's built-in fetchers using the fetchers parameter.

Usage Examples​

Basic Custom Resolver​

This example shows a custom resolver that resolves packages from a custom registry:

.pnpmfile.cjs
const customResolver = {
  // Only handle packages with @company scope
  canResolve: (wantedDependency) => {
    return wantedDependency.alias.startsWith('@company/')
  },

  resolve: async (wantedDependency, opts) => {
    // Fetch metadata from custom registry
    const response = await fetch(
      `https://custom-registry.company.com/${wantedDependency.alias}/${wantedDependency.bareSpecifier}`
    )
    const metadata = await response.json()

    return {
      id: `${metadata.name}@${metadata.version}`,
      resolution: {
        tarball: metadata.tarballUrl,
        integrity: metadata.integrity
      }
    }
  }
}

module.exports = {
  resolvers: [customResolver]
}
Custom Resolver and Fetcher with shouldRefreshResolution​

This example shows a resolver and fetcher working together with a custom resolution type and time-based cache invalidation:

.pnpmfile.cjs
const customResolver = {
  canResolve: (wantedDependency) => {
    return wantedDependency.alias.startsWith('company-cdn:')
  },

  resolve: async (wantedDependency, opts) => {
    const actualName = wantedDependency.alias.replace('company-cdn:', '')
    const version = await fetchVersionFromCompanyCDN(actualName, wantedDependency.bareSpecifier)

    return {
      id: `company-cdn:${actualName}@${version}`,
      resolution: {
        type: 'custom:cdn',
        cdnUrl: `https://cdn.company.com/packages/${actualName}/${version}.tgz`,
        cachedAt: Date.now(), // Custom metadata for shouldRefreshResolution
      },
    }
  },

  shouldRefreshResolution: (depPath, pkgSnapshot) => {
    // Check custom metadata stored in the resolution
    const cachedAt = pkgSnapshot.resolution?.cachedAt
    if (cachedAt && Date.now() - cachedAt > 24 * 60 * 60 * 1000) {
      return true // Re-resolve if cached more than 24 hours ago
    }
    return false
  },
}

const customFetcher = {
  canFetch: (pkgId, resolution) => {
    return resolution.type === 'custom:cdn'
  },

  fetch: async (cafs, resolution, opts, fetchers) => {
    // Delegate to pnpm's standard tarball fetcher
    const tarballResolution = {
      tarball: resolution.cdnUrl,
      integrity: resolution.integrity,
    }

    return fetchers.remoteTarball(cafs, tarballResolution, opts)
  },
}

module.exports = {
  resolvers: [customResolver],
  fetchers: [customFetcher],
}
Basic Custom Fetcher​

This example shows a custom fetcher that fetches certain packages from a different source:

.pnpmfile.cjs
const customFetcher = {
  canFetch: (pkgId, resolution) => {
    return pkgId.startsWith('@company/')
  },

  fetch: async (cafs, resolution, opts, fetchers) => {
    // Delegate to pnpm's tarball fetcher with modified URL
    const tarballResolution = {
      tarball: resolution.tarball.replace(
        'https://registry.npmjs.org/',
        'https://custom-registry.company.com/'
      ),
      integrity: resolution.integrity
    }

    return fetchers.remoteTarball(cafs, tarballResolution, opts)
  }
}

module.exports = {
  fetchers: [customFetcher]
}
Custom Resolution Type with Resolver and Fetcher​

This example shows a custom resolver and fetcher working together with a custom resolution type:

.pnpmfile.cjs
const customResolver = {
  canResolve: (wantedDependency) => {
    return wantedDependency.alias.startsWith('@internal/')
  },

  resolve: async (wantedDependency) => {
    return {
      id: `${wantedDependency.alias}@${wantedDependency.bareSpecifier}`,
      resolution: {
        type: 'custom:internal-directory',
        directory: `/packages/${wantedDependency.alias}/${wantedDependency.bareSpecifier}`
      }
    }
  }
}

const customFetcher = {
  canFetch: (pkgId, resolution) => {
    return resolution.type === 'custom:internal-directory'
  },

  fetch: async (cafs, resolution, opts, fetchers) => {
    // Delegate to pnpm's directory fetcher for local packages
    const directoryResolution = {
      type: 'directory',
      directory: resolution.directory
    }

    return fetchers.directory(cafs, directoryResolution, opts)
  }
}

module.exports = {
  resolvers: [customResolver],
  fetchers: [customFetcher]
}

Priority and Ordering​

When multiple resolvers are registered, they are checked in order. The first resolver where canResolve returns true will be used for resolution. The same applies for fetchers: The first fetcher where canFetch returns true will be used during the fetch phase.

Custom resolvers are tried before pnpm's built-in resolvers (npm, git, tarball, etc.), giving you full control over package resolution.

Performance Considerations​

canResolve(), canFetch(), and shouldRefreshResolution() should be cheap checks (ideally synchronous), as they're called for every dependency during resolution.

関連する設定​

ignorePnpmfile​

  • デフォルト: false
  • タイプ: Boolean

The pnpmfile will be ignored. --ignore-scripts と一緒に使用することで、一切のスクリプトを実行せずにインストールを行うことが可能です。

pnpmfile​

  • Default: ['.pnpmfile.mjs']
  • Type: path[]
  • Example: ['.pnpm/.pnpmfile.mjs']

The location of the local pnpmfile(s).

globalPnpmfile​

  • デフォルト: null
  • タイプ: path
  • Example: ~/.pnpm/global_pnpmfile.mjs

グローバルの pnpmfileの場所。 グローバルの pnpmfile は、インストール時にすべてのプロジェクトで使用されます。

メモ

ローカルの pnpmfiles を使用することをお勧めします。 pnpm をパッケージマネージャとして採用しないプロジェクトで pnpm を使用する場合にのみ、グローバル pnpmfile を使用してください。