Image optimization is a heavy process that is the slowest part of your website build process.
On your local computer, it’s fine because Astro stores the optimized images in node_modules/.astro. So when you build a second time, Astro finds these optimized images and uses them instead of re-optimizing everything.
But if you use GitHub Actions or another Continuous Integration (CI) tool, you will need to cache the assets on that tool. Otherwise, you’ll be wasting a lot of your build time re-optimizing images.
Actual savings in build times
Here’s a build of zellwk.com that contains over 11,000 images. I cleared my GitHub Actions caches and rebuilt all of my assets to give you the actual numbers below:
| Image generation | Total build time | |
|---|---|---|
| Nothing cached | 24m 19s | 25m 45s |
| All 11,394 images cached | 1.7s | 1m 16s |
It saves a lot of time — and it can be the difference between paying for a CI and not paying for one.
Caching images on GitHub Actions
To properly cache images, you need to do two things:
- You need to restore the cache before building
- You need to save the cache after building
In GitHub Actions, the sequence looks like this.
- name: Restore Astro image cache # ...
- name: Build site # ...
- name: Save Astro image cache # ...Here’s the full GitHub Actions code:
# Restore the image cache- name: Restore Astro image cache id: cache-astro-restore uses: actions/cache/restore@v5 with: path: node_modules/.astro key: astro-images-${{ runner.os }}-${{ github.run_id }} restore-keys: | astro-images-${{ runner.os }}-
# Build the site- name: Build site run: npm run build
# Save the image cache- name: Save Astro image cache uses: actions/cache/save@v5 if: always() with: path: node_modules/.astro key: ${{ steps.cache-astro-restore.outputs.cache-primary-key }}Here are a few things you need to know:
- Restoring the cache — We restore the cache from the last run by specifying the
restore-keys. The exact key never matches (every run id is new), so the restore falls back to the newest cache that starts withastro-images-Linux-, which is the one your previous run saved. runner.os— this contains the operating system of the runner,Linuxin this case. This scopes the cache to one OS, so if you ever switch runners, you start with a fresh cache instead of restoring one built on a different OS.github.run_id— GitHub caches are immutable — you can’t overwrite an existing key. Including the run id makes each run save a fresh cache under a new key, so newly optimized images always get persisted.- Saving the cache —
if: always()saves the cache even when a later step fails. If your deploy step errors out, you still keep the optimization work from the build.
Oh, don’t worry about cleaning up the caches. GitHub automatically removes caches that haven’t been accessed for 7 days.
Caching other generated assets
The same pattern works for any directory of build-generated assets. On zellwk.com I run a second restore/save pair for Open Graph images, same steps, just a different path and key prefix:
- name: Restore OG image cache id: cache-og-restore uses: actions/cache/restore@v5 with: path: node_modules/.cache/og-images key: og-images-${{ runner.os }}-${{ github.run_id }} restore-keys: | og-images-${{ runner.os }}-I talk more about generating Open Graph images in the SEO chapter.
Welcome! Unfortunately, you don’t have access to this lesson. To get access, please purchase the course or enroll in Magical Dev School.
Unlock this lesson