メインコンテンツまでスキップ
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 が依存パッケージのマニフェストを解析した後に呼び出されます依存パッケージの 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

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

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.

関連する設定​

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 を使用してください。