DOCSEARCHbyAlgolia
Submit Docs

pnpm Documentation

repository·main·Indexed 43 days ago

https://github.com/pnpm/pnpm.io

A fast, disk space efficient package manager for Node.js. Features include a semi-strict node_modules structure, Plug'n'Play (PnP) support, built-in Node.js version management via pnpm env, and advanced supply chain security controls such as minimumReleaseAge, trustPolicy, and strictDepBuilds.

Tokens
277.9K
Snippets
1.3K
Records
1.7K
Agent score
48%

What's inside pnpm

  1. Overview of pnpr

    main

    pnpr is a pnpm-compatible registry server written in Rust that implements the npm registry protocol. It allows any npm-compatible client (such as pnpm, npm, or yarn) to interact with it.

    Key capabilities include:

    • Multi-ecosystem support: Beyond npm, it supports Cargo (Rust), Python, and the OCI distribution API (container images). This allows publishing multiple package types (e.g., a crate and an npm package) in a single transaction.
    • Security: It uses a router to resolve package names to exactly one origin, preventing dependency-confusion attacks by ensuring there is no cross-origin fall-through.
    • Authentication: Supports OpenID Connect (OIDC) for user sign-in.

    :::caution Experimental

    pnpr is experimental and in active development. Its behavior, configuration, and APIs are subject to change. :::

  2. Overview of pnpr HTTP endpoints

    main

    pnpr exposes several functional surfaces via HTTP endpoints. The availability of these surfaces depends on your configuration:

    • Registry surface: Provides npm-compatible package, publish, and team endpoints. It also supports Cargo, Python, and image protocols. It is served when at least one registry is declared under registries:. Use --disable-registry to turn it off for a single process.
    • Resolver surface (resolver.enabled): Provides install-accelerator endpoints under /-/pnpr.
    • Shared-artifact surface (artifacts.enabled): Provides signed artifact publish, lookup, and blob endpoints under /-/pnpr, plus the compiler cache. This can run without the resolver.
    • Pipeline run surface (pipeline.enabled): Provides pnpm pipeline run records under /-/pnpr.

    All registry paths are available under the / (path-less) base or a /<name>/ prefix. On servers with multiple ecosystems, they are also available under /npm/.

  3. Overview of pnpm settings

    main

    pnpm configuration is organized into several functional groups. Settings can be applied globally, per project, or within a workspace. Major categories include:

    • Dependency Resolution: Controls how versions are selected and overridden (e.g., overrides, packageExtensions).
    • Node-Modules: Configures the structure of node_modules (e.g., nodeLinker, hoist).
    • Store: Manages the content-addressable store and integrity (e.g., storeDir).
    • Lockfile: Configures how the pnpm-lock.yaml is generated and managed.
    • Network & Request: Handles proxies, SSL, and fetch retry logic.
    • Peer Dependencies: Manages how peer dependencies are installed and resolved.
    • CLI & Node.js: Controls CLI output, logging, and the Node.js runtime used by pnpm.
    • Build: Configures how dependency build scripts are executed.
    • Workspace: Specific settings for monorepos, often configured in pnpm-workspace.yaml.

  4. Understand the pnpr license terms

    main

    pnpr is source-available, not open source. It is licensed under the PolyForm Shield License 1.0.0.

    Usage Permissions

    You may run, modify, and self-host pnpr for any purpose except providing a product that competes with pnpr (or with a product the licensor provides using it).

    Commercial Use

    If you require a commercial or non-compete license, you must contact Zoltan Kochan.

    Note on Contributions

    While most of the pnpm monorepo is MIT licensed, contributions to the pnpr/ directory are subject to separate terms. See CONTRIBUTING.md for details.

  5. Manage package owners with pnpm owner

    main

    The pnpm owner command (and its alias pnpm owners) allows you to manage package owners on the registry. This feature was added in v11.1.0.

    Note: Adding or removing owners requires authentication with the registry.

    pnpm owner <subcommand> [args]

  6. Manage pnpm configuration with the config command

    main

    The pnpm config command (alias: pnpm c) allows you to manage pnpm settings across different configuration files.

    Settings are split into two types:

    1. Legacy and npm-compatible registry/authentication settings: Stored in INI files (global rc, auth.ini, and local .npmrc).
    2. pnpm settings: Stored in YAML files (global config.yaml and per-project pnpm-workspace.yaml).

    To find the path to your global YAML configuration file, use:

    pnpm config get globalconfig

  7. Compare pnpm features with npm

    main

    pnpm provides several advanced features that are not available in npm, including:

    • Content-addressable storage: Efficiently manages packages across multiple projects.
    • Plug'n'Play support: Compatible with PnP environments.
    • Patching dependencies: Ability to patch dependencies using pnpm patch.
    • Managing runtimes: Control over different runtimes.
    • Managing versions of itself: pnpm can manage its own versions.
    • Side-effects cache: Optimizes build processes.
    • Catalogs: Centralized dependency management.
    • Config dependencies: Manage dependencies used for configuration.
    • JSR registry support: Native support for the JSR registry.
    • Auto-install before script run: Automatically ensures dependencies are installed before running scripts via verify-deps-before-run.
    • Hooks: Extensibility via pnpmfile.js.
    • Build script security: Enhanced security for build scripts via allow-builds.
    • Listing licenses: View project licenses via pnpm licenses list.

    Common features shared by both include Workspace support, Isolated node_modules, Hoisted node_modules, Autoinstalling peers, Overrides support, Dynamic package execution (using pnx), and SBOM generation.

  8. Use pnpm stage for staged publishing

    main

    The pnpm stage command implements npm's staged publishing workflow. It allows you to upload package tarballs to a staging area instead of the live registry. This lets you verify release artifacts or smoke-test CI before performing the final promotion (which requires 2FA/OTP). Staged versions are not resolved by pnpm install until they are explicitly approved.

    Note: This feature was added in v11.3.0.

    pnpm stage <subcommand> [options]

  9. What is the Global Virtual Store

    main

    By default, pnpm uses a per-project virtual store located in node_modules/.pnpm. This directory contains hardlinks to the content-addressable store. While file contents are shared, the directory structure is duplicated for every project to satisfy Node.js module resolution.

    The global virtual store changes this behavior. Instead of per-project .pnpm directories, pnpm maintains a single shared virtual store (located at <store-path>/links/). Each project's node_modules contains only symlinks pointing into this shared global location. This reduces the time spent creating hardlinks during pnpm install and saves disk space by sharing the directory structure across projects.

    To find your store path, run:

    pnpm store path

  10. What is the Shared Side-effects Cache?

    main

    The Shared Side-effects Cache is a proof-of-concept feature (introduced in pnpr v0.1.0-alpha.8, pnpm v11.25.0 and v12.0.0) that allows a trusted builder to publish the build output of a dependency's lifecycle scripts. Instead of every machine performing the same build, other machines can download and restore the signed, pre-built artifacts from a central pnpr server.

    Key Characteristics:

    • Security: Artifacts are not trusted by default. They must be signed with a P-256 key that the consumer configures independently of the server. The signed payload includes the package name, version, source tarball integrity, and platform compatibility.
    • Reliability: If a server is unreachable, a signature is unverifiable, or a platform is incompatible, pnpm falls back to a local build. It makes installs faster but never causes them to fail.
    • Immutability: Once an artifact is published for a specific input key and compatibility set, it cannot be changed. This ensures consumers always receive the same bytes for a given dependency version.

  11. Ship Platform-specific Binaries in Config Dependencies

    main

    Config dependencies can ship platform-specific binaries using optionalDependencies.

    Each platform-binary package must declare its supported platform using os, cpu, and/or libc fields. pnpm installs only the variant matching the host and symlinks it next to the parent config dependency in the global virtual store. This allows require('my-config-platform-arch') to resolve correctly at runtime. The env lockfile records all variants to ensure portability.

  12. Configure Node-Modules and Hoisting

    main

    pnpm allows fine-grained control over how node_modules are laid out and how dependencies are hoisted:

    Node-Modules Settings

    • nodeLinker: Determines the layout of node_modules (e.g., hoisted, isolated, pnpm).
    • modulesDir: Sets the directory for node_modules.
    • virtualStoreDir: Configures the location of the virtual store.

    Dependency Hoisting Settings

    • hoist: Controls which dependencies are hoisted to the root of node_modules.
    • hoistPattern: A glob pattern specifying which packages to hoist.
    • publicHoistPattern: Specifies packages to hoist to the top level of node_modules for visibility by tools that don't support symlinks.
    • shamefullyHoist: A boolean that, when true, hoists all dependencies to the root (similar to npm/yarn behavior).