Essential CSS
JavaScript Roadmap
Learn JavaScript
Mastering Web Typography
Practical Astro
Understanding Async JS
Unorthodox Tailwind
API Masterclass
Build and Deploy
The Beginner Freelancer
Real World Node
Profile Billing Logout
Practical Astro
Lesson Plan
  1. Content Systems
    1. Introduction
    2. An import alias
    3. Using Markdown
    4. Markdown extended
    5. Markdown component
    6. Markdown component in frameworks
    7. Content collections made easy
    8. Basic blogs
    9. Blogs made easy
    10. Prev/Next navigation
    11. Pagination made easy
    12. Better tag pages
    13. Paginated tag pages
    14. Markdown layouts
    15. Partials
    16. JS over JSON Data
    17. Dynamic 404 pages
    18. Putting everything together
    19. Other useful systems
  2. Image Systems
    1. Introduction
    2. Images are complicated because of this
    3. Astro's Image component
    4. Astro's Picture component
    5. Improvements over Astro's Image and Picture Components
    6. Images in Markdown and MDX
    7. Images in framework components
    8. Background images
    9. Art Direction with Astro
    10. Videos without layout shifts
    11. GIF Replacements and background video
    12. SVGs and icons
    13. SVG backgrounds
    14. Adding noise to images
    15. Asset caching on GitHub Actions
    16. Putting everything together
    17. Other useful systems

Asset caching on GitHub Actions

2m:52s

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:

  1. You need to restore the cache before building
  2. 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:

  1. 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 with astro-images-Linux-, which is the one your previous run saved.
  2. runner.os — this contains the operating system of the runner, Linux in 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.
  3. 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.
  4. 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.