build-cache-s3

Speed up your npx expo run:[android|ios] builds by caching native builds in S3-compatible storage. If a matching cache is found, it downloads and launches the build, skipping native compilation.

Requires Expo SDK 53+

✨ Features

• ⚡️ Fast Builds: Skip native compilation on repeat builds.
• ☁️ S3-Compatible: Works with AWS S3, Cloudflare R2, DigitalOcean Spaces, MinIO, LocalStack, and more.
• Flexible Config: Configure via app.json, app.config.js, build-cache-s3.json, or ENV variables.
• Environment-Aware: Control cache behavior for local and CI/CD environments.

Getting Started

1. Install:

   npm install --save-dev build-cache-s3
   # or
   yarn add --dev build-cache-s3

2. Configure:
   Add to your Expo config under
   Expo 54: buildCacheProvider
   Expo 53: experiments.buildCacheProvider

   {
     "expo": {
       "experiments": {
         "buildCacheProvider": {
           "plugin": "build-cache-s3",
           "options": {
             "bucket": "your-s3-bucket-name",
             "region": "your-aws-region",
             "endpoint": "https://s3.your-aws-region.amazonaws.com",
             "accessKeyId": "hardcoded or preferably use environment variables instead",
             "secretAccessKey": "hardcoded or preferably use environment variables instead"
           }
         }
       }
     }
   }

   Tip: Use environment variables for credentials (accessKeyId, secretAccessKey).

🛠️ Configuration

Property	Description	Env Variable	Required
bucket	S3 bucket for caching builds	BUILD_CACHE_S3_BUCKET	Yes
region	AWS region	BUILD_CACHE_S3_REGION	Yes
endpoint	Custom S3 endpoint (for non-AWS providers)	BUILD_CACHE_S3_ENDPOINT	No
accessKeyId	AWS access key ID	BUILD_CACHE_S3_ACCESS_KEY_ID	No
secretAccessKey	AWS secret access key	BUILD_CACHE_S3_SECRET_ACCESS_KEY	No
forcePathStyle	Use path-style URLs (for some S3 providers)	BUILD_CACHE_S3_FORCE_PATH_STYLE	No
localMode	Local cache mode: read, read-write, no-cache	BUILD_CACHE_S3_LOCAL_MODE	No
ciMode	CI cache mode: read, read-write, no-cache	BUILD_CACHE_S3_CI_MODE	No
localCacheDir	Local cache directory	BUILD_CACHE_S3_CACHE_DIR	No
localCacheGcTimeDays	Days before local cache files are deleted	BUILD_CACHE_S3_CACHE_GC_DAYS	No
debug	Enable debug logging	BUILD_CACHE_S3_DEBUG	No

Configuration Methods

• Expo config: See above.
• Environment variables: Set the required variables in your shell or CI/CD environment.
• Config file: Create build-cache-s3.json in your project or home directory.

  {
    "bucket": "your-s3-bucket-name",
    "region": "your-aws-region"
  }

S3 Bucket Setup

• Use a dedicated bucket for build caching.
• Set a lifecycle policy to auto-delete old builds (e.g., after 7-30 days).

Supported Providers

• AWS S3
• Cloudflare R2 (simple setup with 15GB free tier)
• MinIO
• LocalStack
• DigitalOcean Spaces

For local-only caching, see expo-build-disk-cache.
For remote caching without managing your own S3 storage, see eas-build-cache-provider.

❤️ Acknowledgments

A special thank you to the entire Expo team for their exceptional work and for building a flexible and extensible platform that makes plugins like this possible!