Caching npm dependencies in GitHub Actions with actions/cache

actions/cache saves a directory at the end of a job and restores it at the start of later runs, keyed on a string you choose. For a Node project, that means you don’t download every package from the npm registry on every build.
A minimal example
Section titled “A minimal example”This workflow caches node_modules between builds:
on: push
jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - uses: actions/setup-node@v7 with: node-version: lts/* - uses: actions/cache@v6 with: path: node_modules key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} restore-keys: | ${{ runner.os }}-node- - run: npm install - run: npm testHow the cache step behaves:
- Restore. It looks for a cache whose key exactly matches
Linux-node-<hash of package-lock.json>. If there’s none, it falls back to the most recent cache whose key starts with arestore-keysprefix (Linux-node-), so you still get a mostly up-to-datenode_modulesafter the lockfile changes. - Your steps run.
npm installonly fetches what’s missing or changed. - Save. In a post-job step, if there was no exact key match and the job succeeded, the action saves the directory under the new key. Caches are immutable: an existing key is never overwritten, which is why the lockfile hash belongs in the key.
Caching node_modules vs. the npm cache
Section titled “Caching node_modules vs. the npm cache”The actions/cache docs recommend not caching node_modules: it can break across Node versions (native modules are compiled for a specific one), and it doesn’t work with npm ci, which deletes node_modules before installing. If you do cache it, at least put the Node version in the key.
The simpler option is to let setup-node cache npm’s download cache (~/.npm) for you, keyed on the lockfile:
- uses: actions/setup-node@v7 with: node-version: lts/* cache: npm - run: npm cinpm ci still has to unpack every package into node_modules, but the downloads come from the cache rather than the registry, and you get a clean, lockfile-exact install every time.
The workflow for this blog
Section titled “The workflow for this blog”I added this logic to my personal blog’s GitHub Action to cache node_modules between builds, to save time on the npm install step and reduce the number of requests to the npm registry. Updated to current action versions, plus one line that clears Astro’s content cache (explained under Gotchas), the workflow looks like this:
name: Build For Github# Don't want to burn my private minutes at this pointon: push: branches: - master - main - feature/* schedule: # * is a special character in YAML so you have to quote this string - cron: '30 21 * * 1-6/3'
jobs: make_website: name: Generate Website runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - uses: actions/cache@v6 with: path: node_modules key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} restore-keys: | ${{ runner.os }}-node-
- uses: actions/setup-node@v7 name: Update node with: node-version: lts/*
- name: install astro run: npm install --force
- name: build run: | # The cached node_modules also holds Astro's content cache (node_modules/.astro). # Remove it so every build renders posts from scratch. rm -rf node_modules/.astro npm run build echo > dist/.nojekyll
- name: Deploy 🚀 uses: JamesIves/github-pages-deploy-action@v4 with: token: ${{ secrets.MAIN_REPO_TOKEN }} branch: gh-pages folder: distWhat each part does:
- Triggers. Pushes to
master,mainor anyfeature/*branch, plus a schedule. The cron expression30 21 * * 1-6/3means 21:30 UTC on days of the week 1 through 6 in steps of 3, which is Monday and Thursday. Scheduled workflows only run on the repository’s default branch. - Cache. Restores and saves
node_modulesas described above. setup-node. Installs the current Node.js LTS release.npm install --force.--forcemakes npm fetch packages from the registry even when a local copy exists, and with npm 7+ also lets the install proceed despite peer-dependency conflicts. The first effect partly defeats the cache, so drop--forceif your dependencies resolve cleanly without it.- Build.
npm run buildwrites the static site todist, and the empty.nojekyllfile stops GitHub Pages from running the output through Jekyll, which would drop files and folders starting with_(such as Astro’s_astroasset folder). - Deploy.
JamesIves/github-pages-deploy-actioncommits the contents ofdistto thegh-pagesbranch. In v4 the inputs are lowercase (token,branch,folder); v3 usedGITHUB_TOKEN,BRANCHandFOLDER. Thetokeninput is optional when deploying to the same repository, because the action falls back to the built-inGITHUB_TOKEN; you need a personal access token likeMAIN_REPO_TOKENonly to push to a different repository.
Gotchas
Section titled “Gotchas”- Stale build caches ride along. Anything tools write inside
node_modules(Astro’s.astrocontent cache, Babel or webpack caches undernode_modules/.cache) is restored with it. If a change to your build config doesn’t seem to take effect in CI, that’s the first place to look; that’s what therm -rf node_modules/.astroline above is for. - Caches are scoped by branch. A run can restore caches created on its own branch or on the default branch, but not from sibling feature branches.
- Unused caches are evicted. GitHub removes caches that haven’t been accessed in 7 days, and evicts the oldest ones when a repository exceeds its cache storage limit.
Further reading
Section titled “Further reading”© 2026 David Li · Home · Blog · RSS ·Classic site · Built with Astro, Starlight and three.js · Logos:Font Awesome Free (CC BY 4.0)