DEV Community

Cover image for Cache Composer and npm in GitHub Actions for Laravel
devTalk
devTalk

Posted on Originally published at dev-talk.com

Cache Composer and npm in GitHub Actions for Laravel

Last updated: 12 November 2026. See theupdate logat the end.

Most of the time in a Laravel CI run goes to downloading packages: Composer dependencies on every run, and npm packages whenever you build front-end assets. Each run starts on a clean machine, so without a cache the same files are fetched again and again. This is Part 2 of the series. Part 1 built the test workflow; here we add caching to it, and Part 3 reuses the same steps in the deploy job.

I did not time any run, so there are no speed-up numbers here. What follows is the configuration, why each line exists, and how to confirm the cache is working in your own logs.

What to cache, and what not to

Cache the package manager's download cache, not the installed vendor directory. The setup-php README says it plainly: do not cache vendor with actions/cache, because that has side effects. The download cache is safe, since composer install still runs and builds a correct vendor from the lock file, it just skips the downloads.

Composer

Add two steps before composer install in the test job:

      - name: Find the Composer cache directory
        id: composer-cache
        run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"

      - name: Cache Composer downloads
        uses: actions/cache@v6
        with:
          path: ${{ steps.composer-cache.outputs.dir }}
          key: composer-${{ runner.os }}-php${{ matrix.php }}-${{ hashFiles('composer.lock') }}
          restore-keys: |
            composer-${{ runner.os }}-php${{ matrix.php }}-

      - name: Install Composer dependencies
        run: composer install --prefer-dist --no-interaction --no-progress
Enter fullscreen mode Exit fullscreen mode

The first step asks Composer where its cache lives instead of hardcoding a path. Running that same command from the workflow file locally printed a path ending in composer/files, and the step wrote it as dir=... into the step output:

dir=<home>/composer/files
Enter fullscreen mode Exit fullscreen mode

The second step is actions/cache (v6 at the time of writing). It restores the directory at the start and saves it when the job ends successfully.

How the key works

  • key has the OS, the PHP version from the matrix and a hash of composer.lock. When you change a dependency, the hash changes, so you get a fresh cache entry.
  • restore-keys is a list of prefixes tried in order when the exact key isn't found. After a lock file change, the job restores the most recent cache for the same OS and PHP version, so most packages are still local and Composer only downloads what changed. The action's README describes this as restoring a stale cache when there is no exact match.
  • The PHP version is in the key so each matrix entry has its own cache.

The cache-hit output is true only for an exact key match, and false when a restore-keys entry or nothing was restored, per the action's README. A partial restore is normal and good.

npm

If the job builds assets (Part 3 does), actions/setup-node can cache npm for you:

      - name: Set up Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '24'
          cache: npm

      - name: Build front-end assets
        run: |
          npm ci
          npm run build
Enter fullscreen mode Exit fullscreen mode

With cache: npm the action caches npm's package data and, according to its README, looks for package-lock.json (or npm-shrinkwrap.json, yarn.lock) in the repository root and uses its hash as part of the key. If your lock file is somewhere else, set cache-dependency-path. Use npm ci, not npm install: it installs exactly what the lock file says and fails if package.json and the lock file disagree.

Read the setup-node README for your version before relying on defaults. It describes automatic npm caching when package.json has a packageManager field set to npm, and a package-manager-cache option to turn that off. Being explicit with cache: npm avoids depending on that behavior.

How to confirm it works

  1. Push a commit. The first run should report that no cache was found for your key, and the post-job step saves one.
  2. Push a commit that doesn't touch composer.lock. The cache step should report a hit on the exact key, and Composer should install from local files.
  3. Change a dependency. You should see a restore through restore-keys (not an exact hit), then a new cache saved under the new key.

The exact log wording belongs to the action and can change, so look at the cache step in the run log rather than searching for a fixed string.

Limits and gotchas

  • Size and eviction. The action's README says a repository can hold up to 10 GB of caches, with older entries evicted by last access, and caches not accessed within a week are evicted as well. A small project may never notice; a busy monorepo might.
  • Caches don't update. The tips document in the cache repository states that a cache is immutable. If the key matches, nothing is saved again. That is why the lock file hash goes in the key.
  • Branch scope. The README says caches are scoped to the key, version and branch, and the default branch's cache is available to other branches. A cache written on a feature branch is not visible to other feature branches, so runs on main are what warm the cache for everyone else.
  • A missing lock file means a useless key. hashFiles('composer.lock') is empty if the file doesn't exist, so the key never changes. Commit your lock files.
  • Runner version. The README notes actions/cache v5 and newer run on Node 24 and need Actions Runner 2.327.1 or newer. This only matters on self-hosted runners; GitHub-hosted runners are kept current.

Alternatives

  • Built-in cache in other setup actions. setup-node has its own as shown above. For Composer, the explicit actions/cache step is what the setup-php docs show.
  • Cache the PHP extensions too. The setup-php README has a section on caching extensions. It helps when you compile extensions from PECL, and does little if you only use ones bundled with the image.
  • Skip work instead of caching it. Run the full suite in pull requests, but skip jobs that don't matter for a change with path filters in on:.

Common mistakes

  • Caching vendor instead of Composer's download directory.
  • Using a key without the lock file hash, so the cache is stale forever.
  • Using a key that changes on every run (a timestamp or run number), so nothing is ever restored.
  • Forgetting the PHP version in the key when the matrix runs several versions.
  • Using npm install in CI, which can change the lock file and produce different results from one run to another.

Related Dev Talk articles

Frequently asked questions

Should the cache step go before or after setup-php?

After. The cache path comes from composer config cache-files-dir, so Composer must already exist, and setup-php installs it.

What if I suspect a bad cache entry?

Change the key prefix (for example composer-v2-...). Entries are immutable, so a new prefix is the simplest way to start from an empty cache. You can also delete caches from the repository's Actions settings.

Does the deploy job in Part 3 reuse this cache?

It uses the same key format with PHP 8.4, so it should match the entry the PHP 8.4 test job saved, subject to the branch scope rules above. I did not observe this on GitHub, so check the cache step in your own deploy log.

Update log

  • 12 November 2026: first version.
  • To recheck on each update: the current major versions of actions/cache and actions/setup-node, the cache size and eviction limits, and the setup-node automatic caching defaults.

Sources


Originally published on DEV Talk.

Top comments (0)