Offline and sandboxed builds are a common headache for JavaScript teams. Security-conscious CI systems, air-gapped networks and reproducible build tools often download every source archive first, then run the build with no network access. Registry packages were already easy to handle that way with pnpm, but dependencies on a tarball URL or a git host such as GitHub were not.

pnpm 12.21.0 fixes that gap. When you run pnpm store add inside a project, it now reads the lockfile and prepares downloaded tarballs for every lockfile entry that pins them, including tarball-URL and git-hosted dependencies. Then pnpm install --offline --frozen-lockfile can install everything without touching the network. The same release also makes repeated installs keep their peer dependency choices, which removes a source of noisy lockfile diffs.

This tutorial walks through an offline build step by step and explains the peer dependency changes.

What changed in pnpm 12.21

From the release notes:

  • pnpm store add prepares tarballs for every lockfile entry that pins them. Besides registry packages, an offline frozen install can now handle dependencies on a tarball URL, and dependencies on a git host whose lockfile entry records an integrity.
  • Stable peer dependency providers. Repeated installs no longer change the peer provider that the previous install chose, whether you add, update or remove a dependency.
  • Lockfile fixes. pnpm can now read a lockfile with a mapping key longer than 1,024 characters written as 'key':. Before, it failed with ERR_PNPM_BROKEN_LOCKFILE. Several lockfile.format: v13, nodeLinker: hoisted and pnpm deploy failures are also fixed.

Upgrade first:

pnpm self-update 12.21.0
pnpm --version

If you manage pnpm through the packageManager field in package.json, set it to [email protected] instead, so everyone on the team gets the same version.

How pnpm store add works

According to the pnpm store docs, pnpm store add is “functionally equivalent to pnpm add, except this adds new packages to the store directly without modifying any projects or files outside of the store.”

It can also take tarballs that were downloaded some other way, or directories of them. It searches directories recursively for .tgz, .tar.gz and .tar files.

The important part is where you run it:

  • Inside the project, it reads the project’s lockfile and prepares each tarball for every entry that pins it. That covers tarball URLs, packages from a named registry, and git-hosted dependencies whose entry records an integrity.
  • Outside a project, a tarball only serves registry entries that match the name and version in its own package.json.

An install takes a package from such a tarball when its lockfile entry pins that tarball. The entry’s integrity can be the tarball’s sha512 or sha1, or the hash of the uncompressed tar inside it (which lockfile.integrityTarget: tar records).

Step 1: A project with mixed dependency sources

Imagine a package.json like this:

{
  "name": "offline-demo",
  "private": true,
  "packageManager": "[email protected]",
  "dependencies": {
    "express": "^5.1.0",
    "internal-ui": "https://files.example.com/internal-ui-2.3.0.tgz",
    "date-utils": "github:example-org/date-utils#v1.4.0"
  }
}

Here express comes from the npm registry, internal-ui from a tarball URL and date-utils from GitHub. (The URL and repo names are placeholders; use your own.)

On a machine with network access, create the lockfile:

pnpm install
git add pnpm-lock.yaml

Commit the lockfile. The offline build depends on it.

Step 2: Download the tarballs ahead of time

How you collect the tarballs depends on your build system. Many sandboxed build tools have their own fetch step. For a simple example, you can download them with curl into a tarballs/ folder:

mkdir -p tarballs
curl -fsSL -o tarballs/internal-ui-2.3.0.tgz \
  https://files.example.com/internal-ui-2.3.0.tgz
# ...plus registry tarballs and the GitHub archive your build system fetched

The file names don’t matter much; what matters is that each archive matches the integrity recorded in the lockfile.

Step 3: Prepare the store, then install offline

Now move into the sandbox (no network) and, from the project directory, run:

pnpm store add ./tarballs
pnpm install --offline --frozen-lockfile
  • pnpm store add ./tarballs scans the folder, matches archives to lockfile entries and prepares them in the store.
  • --offline tells pnpm to use only what is in the store.
  • --frozen-lockfile makes the install fail instead of changing pnpm-lock.yaml, which is exactly what you want in CI.

Before 12.21, the tarball-URL and git-hosted entries were the ones that could fail here. Now they install from the prepared store.

Using a dedicated store directory

In a sandbox you often want the store inside the build directory rather than the user’s home. Point pnpm at it explicitly, and use the same location for both commands:

export PNPM_STORE=$PWD/.pnpm-store
pnpm store add ./tarballs --store-dir "$PNPM_STORE"
pnpm install --offline --frozen-lockfile --store-dir "$PNPM_STORE"
pnpm store path --store-dir "$PNPM_STORE"

pnpm store path prints the store location, which is handy when you’re debugging a “package not found in store” error.

Step 4: Use it in a Dockerfile

Here is a pattern for an image build that installs from pre-fetched tarballs. It starts from the official pnpm image used in the pnpm Docker docs; pick the Node.js version you deploy:

FROM ghcr.io/pnpm/pnpm:12
RUN pnpm runtime set node 22 -g
WORKDIR /app

# Lockfile and manifests first, for layer caching
COPY package.json pnpm-lock.yaml ./
# Tarballs fetched earlier by your CI system
COPY tarballs ./tarballs

RUN pnpm store add ./tarballs \
 && pnpm install --offline --frozen-lockfile --prod

COPY . .
CMD ["node", "server.js"]

If your registry dependencies aren’t in tarballs/, run pnpm fetch in a stage that does have network access. It downloads packages from the lockfile into the store, and a later pnpm install --offline can use them.

Peer dependencies now stay put

The second big change in 12.21 is quieter but useful in large repos. Before, adding or updating an unrelated dependency could make pnpm choose a different peer provider on the next install, producing lockfile churn and occasionally a different runtime version of a peer.

The release notes say repeated installs now keep the peer providers chosen by the previous install. This covers:

  • adding, updating or removing a dependency,
  • projects that use different ranges of one dependency,
  • dependency cycles,
  • injected dependencies with autoInstallPeers: false.

An unchanged install keeps a valid locked peer provider even when a direct dependency provides another compatible version. When you explicitly run pnpm add or pnpm update, that request still wins.

Two related fixes: workspace projects that pick different versions of a peer provider no longer share one copy of the package that depends on it, and a removed dependency no longer comes back as a peer provider.

A quick way to see the benefit is to add a small dev dependency and inspect the diff:

pnpm add -D prettier
git diff --stat pnpm-lock.yaml

On 12.21 you should mostly see entries for the new package, without unrelated peer changes.

Other fixes worth knowing

  • frozenStore with nodeLinker: hoisted no longer fails with ERR_PNPM_FROZEN_STORE_NEEDS_BUILD.
  • pnpm deploy with lockfile.format: v13 no longer fails when injected workspace packages have hashed peer bindings.
  • pnpm setup now supports PowerShell as the login shell on Linux and macOS.
  • pnpr: if a pnpr server refuses a setting, pnpm prints a warning and resolves locally.

Takeaway

If you build JavaScript projects in sandboxes, air-gapped networks or locked-down CI, pnpm 12.21 removes a real blocker: tarball-URL and git-hosted dependencies can now be installed offline after pnpm store add, as long as you run it inside the project so it can read the lockfile. Pair it with pnpm install --offline --frozen-lockfile for fully reproducible builds, and enjoy fewer surprise peer dependency changes in your lockfile diffs.