pnpm/pkg-manager/core/README.md

@pnpm/core

Fast, disk space efficient installation engine. Used by pnpm

Install

Install it via npm.

pnpm add @pnpm/core

It also depends on @pnpm/logger version 1, so install it as well via:

pnpm add @pnpm/logger@1

API

mutateModules(importers, options)

TODO

link(linkFromPkgs, linkToModules, [options])

Create symbolic links from the linked packages to the target package's node_modules (and its node_modules/.bin).

Arguments:

• 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?: (wantedDependency: WantedDependency, wantedLockfile: LockfileObject) => 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(wantedDependency, wantedLockfile) - Return true to trigger full resolution of all packages (skipping the "Lockfile is up to date" optimization). The lockfile contents are provided to enable comparisons with the latest resolved version.

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: (wantedDependency) => {
    // You can implement custom logic to determine if re-resolution is needed
    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