Task Caching, PNPM Catalog, and Lockfile Changes

[kevinswarner]

I have searched for an answer for this, but find conflicting and incomplete information. I am hoping someone here can help me with this. We have a monorepo using pnpm workspaces. We have several workspaces, each with tasks such as "typecheck", "lint", "test" and "build". Up to this point, Nx caching has been working nicely with default setup. For example, if we make a change to something inside on of the workspaces, the cache will be invalidated for most of those tasks, and Nx will run the task again with fresh results. This has helped us greatly in speeding up our local development workflow as well as our CI jobs.

But, I wanted to move to using pnpm catalogs for managing dependencies used by multiple workspaces. This would be good for us because we could more easily ensure we are using consistent versions and be able to more easily address package vulnerabilities. The problem I am hitting is that if I make a change to a dependency version in the pnpm-workspace.yml file, and do a fresh pnpm install, I still get cache hits when running nx commands on my workspaces, even if the change I made would result in an actual typecheck error or test error in some workspaces.

So then I decided to add the lock file as an input to those tasks, but now, if a change is made that results in the lock file getting updated, but the change really only would affect one workspace, the Nx cache produces cache misses for all workspaces. This it too aggressive.

I am stuck between missing important issues because of cache hits, or slowing down our workflow because of unnecessary cache hits. Is there a recommended approach for this scenario or maybe a feature I am missing?

Thanks! --Kevin

[apoorva-01]

Drop the lockfile input. That's the "too aggressive" part. A file input is all-or-nothing: the lockfile is one file, so any change to it busts the hash of every task that includes it. There's no way to make it granular.

You don't need it either. Nx already folds external dependencies into a task's hash. What you want is to scope which packages each task cares about, and the tool for that is a per-target externalDependencies input:

"targets": {
  "typecheck": {
    "inputs": ["default", { "externalDependencies": ["typescript"] }]
  },
  "test": {
    "inputs": ["default", { "externalDependencies": ["vitest", "@testing-library/react"] }]
  }
}

It hashes the resolved version of those packages from the lockfile, so bumping typescript in the catalog and running pnpm install only misses the tasks that actually declared typescript. Everyone else stays cached. That's the granularity you're after, without the lockfile sledgehammer.

One thing that's probably the real cause of the stale hits: catalog: resolution in the project graph only landed in Nx 22. On anything older, a version change in pnpm-workspace.yaml never gets traced to the projects using it, so you get cache hits on code that would actually break. So step one is confirm you're on 22+, then add the scoped inputs. The version does reach the lockfile after pnpm install, so once Nx can read it, the hashing lines up.

[rodri-oliveira-dev]

One important caveat to the externalDependencies approach mentioned above: explicitly specifying dependencies narrows what Nx considers when computing the task hash.

That improves cache precision, but it also means you need to include all packages that can influence the task, not just the most obvious ones.

For example, a typecheck task might depend on typescript, type definitions, and other tooling that affects compilation.

I'd suggest validating the configuration with a small reproducible test:

1. Pick two projects with different dependency sets.
2. Change a catalog version used by only one project.
3. Run pnpm install to update the lockfile.
4. Execute both targets and inspect their cache behavior.

The expected result is a cache miss for the affected task without unnecessarily invalidating unrelated tasks.

Also, check the effective task inputs using:

nx show project <project-name> --web

This helps identify whether a target's inputs have been overridden by project-level configuration.

If cache hits remain incorrect after upgrading to a version that supports PNPM catalogs, I'd recommend creating a minimal reproduction before adding the entire lockfile as a global input.

The goal is not simply maximizing cache hits, but ensuring that every cache hit is valid.

Reference: [Nx — Inputs and Named Inputs](https://nx.dev/docs/reference/inputs).