Fix pnpm interaction with custom cache (#1522)

* Fix pnpm interaction with custom cache

When a `cacheDirectories` field is set in `package.json`, this triggers [custom cache behavior](https://devcenter.heroku.com/articles/nodejs-classic-buildpack-builds#custom-caching) in the buildpack. This is often used with tools that produce their own specialized caches like Next.js which can cache asset compilation results.

Since custom cache behavior means the user is taking full control of what needs to be cached, the `node_modules` folder is typically added to the cache directory list to ensure that installed modules are also cached. For npm and Yarn this doesn't present a problem but, for pnpm, [the `node_modules` folder is used differently](https://pnpm.io/motivation#creating-a-non-flat-node_modules-directory) and, if the folder already exists (e.g.; on cache restore), it will cause the build to halt with an `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY` error.

After examining the custom cache code, I'm certain that even how npm and Yarn handle this scenario is incorrect. The user should never cache the `node_modules` folder. What should happen instead is (for default or custom cache behavior), the npm cache, Yarn cache, and pnpm store are what should be always cached unless `NODE_MODULES_CACHE=false`. For now, I'm just going to address this pnpm case though. This PR makes the following changes:

### Custom Cache Behavior with pnpm

- if `node_modules` is specified, it will be ignored
- all other cache directories will be processed
- the pnpm store will be inserted into the custom cache list

### pnpm Reporter

A `PNPM_INSTALL_REPORTER` environment variable was introduced to allow for more detailed pnpm output to be produced during install. If set it, the value of this environment variable will be used to append the [`--reporter`](https://pnpm.io/cli/install#--reportername) argument when `pnpm install` is executed. This is used by the tests in this PR to ensure that the pnpm store is functioning correctly, but it could also be useful when debugging builds where pnpm installs are failing unexpectedly.

* Use explicit comparison of `PNPM` variable to `true`

* Use a more precise pattern for matching the `node_modules` folder

* Fix typo

* Validate the PNPM_INSTALL_REPORTER env var

* Update CHANGELOG.md

Signed-off-by: Colin Casey <[email protected]>

* Fix test output validations

---------

Signed-off-by: Colin Casey <[email protected]>

Author: colincasey

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Fix for pnpm + custom caching. ([#1522](https://github.com/heroku/heroku-buildpack-nodejs/pull/1522))
 
 ## [v322] - 2025-12-11
 

bin/compile

@@ -339,7 +339,7 @@ restore_cache() {
     if [[ "$cache_directories" == "" ]]; then
       restore_default_cache_directories "$BUILD_DIR" "$CACHE_DIR" "$YARN_CACHE_FOLDER" "$NPM_CONFIG_CACHE" "$PNPM_CONFIG_CACHE"
     else
-      restore_custom_cache_directories "$BUILD_DIR" "$CACHE_DIR" "$cache_directories"
+      restore_custom_cache_directories "$BUILD_DIR" "$CACHE_DIR" "$PNPM_CONFIG_CACHE" "$cache_directories"
     fi
   elif [[ "$cache_status" == "new-signature" ]]; then
     header "Restoring cache"
@@ -414,7 +414,7 @@ cache_build() {
     save_default_cache_directories "$BUILD_DIR" "$CACHE_DIR" "$YARN_CACHE_FOLDER" "$NPM_CONFIG_CACHE" "$PNPM_CONFIG_CACHE"
   else
     header "Caching build"
-    save_custom_cache_directories "$BUILD_DIR" "$CACHE_DIR" "$cache_directories"
+    save_custom_cache_directories "$BUILD_DIR" "$CACHE_DIR" "$PNPM_CONFIG_CACHE" "$cache_directories"
   fi
   save_signature "$CACHE_DIR"
   build_data::set_duration "save_cache_time" "$cache_build_start_time"

lib/cache.sh

@@ -108,13 +108,16 @@ restore_custom_cache_directories() {
   local cache_directories
   local build_dir=${1:-}
   local cache_dir=${2:-}
+  local pnpm_cache_dir=${3:-}
   # Parse the input string with multiple lines: "a\nb\nc" into an array
-  mapfile -t cache_directories <<< "$3"
+  mapfile -t cache_directories <<< "$4"
 
-  echo "Loading ${#cache_directories[@]} from cacheDirectories (package.json):"
+  echo "Loading from cacheDirectories (package.json):"
 
   for cachepath in "${cache_directories[@]}"; do
-    if [ -e "$build_dir/$cachepath" ]; then
+    if [[ "$PNPM" == "true" ]] && [[ "$cachepath" =~ ^node_modules(/|$) ]]; then
+      echo "- $cachepath (skipping because pnpm is used)"
+    elif [ -e "$build_dir/$cachepath" ]; then
       echo "- $cachepath (exists - skipping)"
     else
       if [ -e "$cache_dir/node/cache/$cachepath" ]; then
@@ -126,6 +129,15 @@ restore_custom_cache_directories() {
       fi
     fi
   done
+
+  if [[ "$PNPM" == "true" ]] && [ -e "$cache_dir/node/cache/pnpm/store" ]; then
+    echo "- pnpm store (included because pnpm is used)"
+    # the $pnpm_cache_dir is created at the start of the build so, now, if we want to
+    # rename the cache directory to $pnpm_cache_dir, we have to remove it or we'll
+    # end up with a $pnpm_cache_dir/store directory instead of $pnpm_cache_dir.
+    rm -rf "$pnpm_cache_dir"
+    mv "$cache_dir/node/cache/pnpm/store" "$pnpm_cache_dir"
+  fi
 }
 
 clear_cache() {
@@ -192,13 +204,16 @@ save_custom_cache_directories() {
   local cache_directories
   local build_dir=${1:-}
   local cache_dir=${2:-}
+  local pnpm_cache_dir=${3:-}
   # Parse the input string with multiple lines: "a\nb\nc" into an array
-  mapfile -t cache_directories <<< "$3"
+  mapfile -t cache_directories <<< "$4"
 
-  echo "Saving ${#cache_directories[@]} cacheDirectories (package.json):"
+  echo "Saving cacheDirectories (package.json):"
 
   for cachepath in "${cache_directories[@]}"; do
-    if [ -e "$build_dir/$cachepath" ]; then
+    if [[ "$PNPM" == "true" ]] && [[ "$cachepath" =~ ^node_modules(/|$) ]]; then
+      echo "- $cachepath (skipping because pnpm is used)"
+    elif [ -e "$build_dir/$cachepath" ]; then
       echo "- $cachepath"
       mkdir -p "$cache_dir/node/cache/$cachepath"
       cp -a "$build_dir/$cachepath" "$(dirname "$cache_dir/node/cache/$cachepath")"
@@ -207,6 +222,12 @@ save_custom_cache_directories() {
     fi
   done
 
+  if [[ "$PNPM" == "true" ]] && [ -e "$pnpm_cache_dir" ]; then
+    echo "- pnpm store (included because pnpm is used)"
+    mkdir -p "$cache_dir/node/cache/pnpm"
+    cp -a "$pnpm_cache_dir" "$cache_dir/node/cache/pnpm/store"
+  fi
+
   build_data::set_raw "has_custom_cache_dirs" "true"
 }
 

lib/dependencies.sh

@@ -305,7 +305,21 @@ pnpm_install() {
   echo "Running 'pnpm install' with pnpm-lock.yaml"
   cd "$build_dir" || return
 
-  monitor "install_dependencies" pnpm install --prod=false --frozen-lockfile 2>&1
+  pnpm_install_args=("install" "--prod=false" "--frozen-lockfile")
+
+  if [ -n "$PNPM_INSTALL_REPORTER" ]; then
+    case "$PNPM_INSTALL_REPORTER" in
+      default|ndjson|append-only|silent)
+        pnpm_install_args+=("--reporter=$PNPM_INSTALL_REPORTER")
+        ;;
+      *)
+        echo "Warning: Invalid PNPM_INSTALL_REPORTER value '$PNPM_INSTALL_REPORTER'. Valid values: default, ndjson, append-only, silent"
+        echo "Proceeding with default reporter"
+        ;;
+    esac
+  fi
+
+  monitor "install_dependencies" pnpm "${pnpm_install_args[@]}" 2>&1
 
   # prune the store when the counter reaches zero to clean up errant package versions which may have been upgraded/removed
   counter=$(load_pnpm_prune_store_counter "$cache_dir")

test/fixtures/pnpm-custom-cache/data/cached-file.txt

@@ -0,0 +1 @@
+Just a simple cached file :)

test/fixtures/pnpm-custom-cache/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "pnpm-custom-cache",
+  "packageManager": "[email protected]",
+  "dependencies": {
+    "dotenv": "^17.2.3"
+  },
+  "cacheDirectories": [
+    "node_modules",
+    "data"
+  ]
+}

test/fixtures/pnpm-custom-cache/pnpm-lock.yaml

@@ -557,7 +557,7 @@ testBuildWithUserCacheDirectoriesCamel() {
   assertCapturedSuccess
 
   compile "cache-directories-camel" $cache
-  assertCaptured "Loading 3 from cacheDirectories"
+  assertCaptured "Loading from cacheDirectories"
   assertCaptured "- server/node_modules"
   assertCaptured "- client/node_modules"
   assertCaptured "- non/existent (not cached - skipping)"
@@ -963,13 +963,13 @@ testBuildWithUserCacheDirectories() {
   cache=$(mktmpdir)
 
   compile "cache-directories" $cache
-  assertCaptured "Saving 2 cacheDirectories"
+  assertCaptured "Saving cacheDirectories"
   assertEquals "1" "$(ls -1 $cache/node/cache | grep -c bower_components | tr -d ' ')"
   assertEquals "1" "$(ls -1 $cache/node/cache | grep -c node_modules | tr -d ' ')"
   assertCapturedSuccess
 
   compile "cache-directories" $cache
-  assertCaptured "Loading 2 from cacheDirectories"
+  assertCaptured "Loading from cacheDirectories"
   assertCaptured "- node_modules"
   assertCaptured "- bower_components"
   assertCapturedSuccess
@@ -1716,6 +1716,28 @@ testCorepackNpmRegistryKeyFix() {
 
 # PNPM
 
+testPnpmWithCustomCache() {
+  cache_dir=$(mktmpdir)
+  env_dir=$(mktmpdir)
+  echo "ndjson" > "$env_dir/PNPM_INSTALL_REPORTER"
+
+  compile "pnpm-custom-cache" "$cache_dir" "$env_dir"
+  assertCaptured "pnpm:fetching-progress"
+  assertCaptured "Saving cacheDirectories (package.json):"
+  assertCaptured "- node_modules (skipping because pnpm is used)"
+  assertCaptured "- data"
+  assertCaptured "- pnpm store (included because pnpm is used)"
+  assertCapturedSuccess
+
+  compile "pnpm-custom-cache" "$cache_dir" "$env_dir"
+  assertCaptured " Loading from cacheDirectories (package.json):"
+  assertCaptured "- node_modules (skipping because pnpm is used)"
+  assertCaptured "- data (exists - skipping)"
+  assertCaptured "- pnpm store (included because pnpm is used)"
+  assertNotCaptured "pnpm:fetching-progress"
+  assertCapturedSuccess
+}
+
 testPnpm7Pnp() {
   build_dir=$(mktmpdir)
   cache_dir=$(mktmpdir)