linkFromPkgs - String[] - paths to the packages that should be linked.
linkToModules - String - path to the dependent package's node_modules directory.
options.reporter - Function - A function that listens for logs.

`linkToGlobal(linkFrom, options)`

Create a symbolic link from the specified package to the global node_modules.

Arguments:

linkFrom - String - path to the package that should be linked.
globalDir - String - path to the global directory.
options.reporter - Function - A function that listens for logs.

`linkFromGlobal(pkgNames, linkTo, options)`

Create symbolic links from the global pkgNames to the linkTo/node_modules folder.

Arguments:

pkgNames - String[] - packages to link.
linkTo - String - package to link to.
globalDir - String - path to the global directory.
options.reporter - Function - A function that listens for logs.

`storeStatus([options])`

Return the list of modified dependencies.

Arguments:

options.reporter - Function - A function that listens for logs.

Returns: Promise<string[]> - the paths to the modified packages of the current project. The paths contain the location of packages in the store, not in the projects node_modules folder.

`storePrune([options])`

Remove unreferenced packages from the store.

Hooks

Hooks are functions that can step into the installation process. All hooks can be provided as arrays to register multiple hook functions.

`readPackage(pkg: Manifest, context): Manifest | Promise<Manifest>`

This hook is called with every dependency's manifest information. The modified manifest returned by this hook is then used by @pnpm/core during installation. An async function is supported.

Arguments:

pkg - The dependency's package manifest.
context.log(message) - A function to log debug messages.

Example:

const { installPkgs } = require('@pnpm/core')

installPkgs({
  hooks: {
    readPackage: [readPackageHook]
  }
})

function readPackageHook (pkg, context) {
  if (pkg.name === 'foo') {
    context.log('Modifying foo dependencies')
    pkg.dependencies = {
      bar: '^2.0.0',
    }
  }
  return pkg
}

`preResolution(context, logger): Promise<void>`

This hook is called after reading lockfiles but before resolving dependencies. It can modify lockfile objects.

Arguments:

context.wantedLockfile - The lockfile from pnpm-lock.yaml.
context.currentLockfile - The lockfile from node_modules/.pnpm/lock.yaml.
context.existsCurrentLockfile - Boolean indicating if current lockfile exists.
context.existsNonEmptyWantedLockfile - Boolean indicating if wanted lockfile exists and is not empty.
context.lockfileDir - Directory containing the lockfile.
context.storeDir - Location of the store directory.
context.registries - Map of registry URLs.
logger.info(message) - Log an informational message.
logger.warn(message) - Log a warning message.

`afterAllResolved(lockfile: Lockfile): Lockfile | Promise<Lockfile>`

This hook is called after all dependencies are resolved. It receives and returns the resolved lockfile object. An async function is supported.

Arguments:

lockfile - The resolved lockfile object that will be written to pnpm-lock.yaml.

Custom Resolvers and Fetchers

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

Custom Resolvers: Convert package descriptors (e.g., foo@^1.0.0) into resolutions
Custom Fetchers: Completely handle fetching for custom package types

Custom Resolver Interface:

interface CustomResolver {
  // Resolution phase
  canResolve?: (wantedDependency: WantedDependency) => boolean | Promise<boolean>
  resolve?: (wantedDependency: WantedDependency, opts: ResolveOptions) => ResolveResult | Promise<ResolveResult>

  // Force resolution check
  shouldForceResolve?: (depPath: string, pkgSnapshot: PackageSnapshot) => boolean | Promise<boolean>
}

Custom Fetcher Interface:

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

Custom Resolver Methods:

canResolve(wantedDependency) - Returns true if this resolver can resolve the given package descriptor
resolve(wantedDependency, opts) - Resolves a package descriptor to a resolution. Should return an object with id and resolution
shouldForceResolve(depPath, pkgSnapshot) - Return true to trigger full resolution of all packages (skipping the "Lockfile is up to date" optimization). The depPath is the package identifier (e.g., lodash@4.17.21) and pkgSnapshot provides direct access to the lockfile entry (resolution, dependencies, etc.).

Custom Fetcher Methods:

canFetch(pkgId, resolution) - Returns true if this fetcher can handle fetching for the given resolution
fetch(cafs, resolution, opts, fetchers) - Completely handles fetching the package contents. Receives the content-addressable file system (cafs), the resolution, fetch options, and pnpm's standard fetchers for delegation. Must return a FetchResult with the package files.

Example - Reusing pnpm's fetcher utilities:

// .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 shouldForceResolve
      },
    }
  },

  shouldForceResolve: (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
    // Transform the custom resolution to a standard tarball resolution
    const tarballResolution = {
      tarball: resolution.cdnUrl,
      integrity: resolution.integrity,
    }

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

// Export as top-level arrays
module.exports = {
  resolvers: [customResolver],
  fetchers: [customFetcher],
}

Delegating to Standard Fetchers:

The fetchers parameter passed to the custom fetcher's fetch method provides access to pnpm's standard fetchers for delegation:

fetchers.remoteTarball - Fetch from remote tarball URLs
fetchers.localTarball - Fetch from local tarball files
fetchers.gitHostedTarball - Fetch from GitHub/GitLab/Bitbucket tarballs
fetchers.directory - Fetch from local directories
fetchers.git - Fetch from git repositories

See the test cases in resolving/default-resolver/test/customResolver.ts and fetching/pick-fetcher/test/pickFetcher.ts for complete working examples.

Notes:

Multiple custom resolvers and fetchers can be registered; they are tried in order until one matches
All methods support both synchronous and asynchronous implementations
Custom resolvers are tried before pnpm's built-in resolvers (npm, git, tarball, etc.)
Custom fetchers can delegate to pnpm's standard fetchers via the fetchers parameter to avoid reimplementing common fetch logic
The shouldForceResolve hook allows fine-grained control over when packages should be re-resolved

Performance Considerations:

canResolve() should be a cheap check (ideally synchronous) as it's called for every dependency during resolution
resolve() can be an expensive async operation (e.g., network requests) as it's only called for matching dependencies
If your canResolve() implementation is expensive, performance may be impacted during large installations

License

MIT