Add Astro Build Cache Support

[kadykov]

Fixes #89

Overview

This PR adds support for caching Astro's build artifacts (optimized images and other assets) between workflow runs, significantly improving build performance for subsequent runs.

Problem

As discussed in #89, Astro maintains its own cache directory (default: node_modules/.astro) that stores optimized images and other build artifacts. Without caching this directory, every workflow run needs to re-optimize the same images, which can add significant time to builds - especially for sites with many images.

While actions/setup-node caches the npm package store, it does not cache Astro's build artifacts, which live in node_modules/.astro.

Solution

This PR implements automatic caching of Astro's build directory using actions/cache:

• Cache Restore: Before the build step, the action attempts to restore the Astro cache from previous runs
• Cache Save: After a successful build, the action saves the Astro cache for future runs
• Smart Cache Keys: Uses astro-cache-${runner.os}-${github.sha} with fallback to astro-cache-${runner.os}- to allow reusing caches across commits while maintaining OS-specific caches

Changes

New Inputs

1. cache (optional, default: "true")

   • Enable or disable Astro build caching
   • Set to "false" to disable caching (useful for debugging)

2. cache-dir (optional, default: "node_modules/.astro")

   • Path to the Astro cache directory (relative to path input)
   • Allows customization if users have configured a custom cacheDir in their Astro config

Implementation Details

• Uses actions/cache/restore@v5.0.1 to restore cache before build
• Uses actions/cache/save@v5.0.1 to save cache after build (only if cache wasn't hit)
• Cache is OS-specific to ensure compatibility
• Works with all supported package managers (npm, yarn, pnpm, bun, deno)

Testing

Test Methodology

1. Created a test Astro project with images requiring optimization
2. Set up a deployment workflow using this action with cache: "true"
3. Made multiple commits to trigger sequential workflow runs
4. Observed that:
   • First run: All images were optimized from scratch
   • Subsequent runs: Previously optimized images show "(reused cache entry)"
   • Build times improved for subsequent runs

Test Results

Evidence of caching working: Workflow Run #58564230627

Key log lines showing cache reuse:

  generating optimized images 
18:24:11   ▶ /_astro/300_Z1muf00.webp (reused cache entry) (+3ms) (1/3)
18:24:11   ▶ /_astro/300_Z1ESw9V.webp (reused cache entry) (+3ms) (2/3)
18:24:12   ▶ /_astro/300_Z1XhNjR.webp (before: 12kB, after: 12kB) (+889ms) (3/3)
18:24:12 ✓ Completed in 890ms.

Cache Behavior Verified

• ✅ Cache is created on first build
• ✅ Cache is restored on subsequent builds
• ✅ Previously optimized images are reused (not re-optimized)
• ✅ New/modified images are optimized and added to cache
• ✅ Cache works across commits (using restore-keys fallback)

Backwards Compatibility

This change is fully backwards compatible:

• Caching is enabled by default but can be disabled with cache: "false"
• All existing workflows will continue to work without modifications
• Users automatically benefit from improved build performance
• No breaking changes to any inputs or outputs

Usage Examples

Default (caching enabled)

- uses: withastro/action@v6
  # Caching is enabled by default, no changes needed!

Explicitly enable caching

- uses: withastro/action@v6
  with:
    cache: "true"

Disable caching (for debugging)

- uses: withastro/action@v6
  with:
    cache: "false"

Custom cache directory

- uses: withastro/action@v6
  with:
    cache: "true"
    cache-dir: "custom-cache-dir"

[Copilot]

Pull request overview

This PR adds automatic caching of Astro's build artifacts to improve build performance across workflow runs. The implementation enables caching by default while maintaining full backward compatibility.

Key Changes:

• Added two new optional inputs: cache (enable/disable caching, defaults to "true") and cache-dir (custom cache directory path, defaults to "node_modules/.astro")
• Integrated actions/cache/restore and actions/cache/save steps into the build workflow
• Updated documentation to describe the new caching inputs

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
action.yml	Added cache input definitions and implemented cache restore/save steps around the build process
README.md	Added documentation for the new cache and cache-dir input parameters

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.