A remote build cache provider plugin for Expo that uses GitHub Releases to store and retrieve cached build artifacts, dramatically accelerating your local development workflow.
This library implements Expo's remote build cache provider interface using GitHub Releases as the storage backend. Build caching is an experimental Expo feature that speeds up npx expo run:ios and npx expo run:android commands by caching builds remotely based on your project's fingerprint.
When you run local development builds with npx expo run:[android|ios], this plugin:
- Checks for existing builds: Searches GitHub Releases for a cached build matching your project's current fingerprint
- Downloads if available: If a matching build exists, downloads and launches it instead of compiling from scratch
- Uploads new builds: If no cache exists, compiles normally and uploads the resulting binary to GitHub Releases for future use
This integration with Expo's build caching system can save significant time during development, especially for large projects or when switching between branches with similar dependencies. Instead of waiting for full compilation every time, you can reuse previously built binaries when your project's fingerprint hasn't changed.
To install the Expo GitHub Cache plugin, you can use a package manager like npm or bun. This plugin is available as an NPM package, making it easy to integrate into your Expo project.
npm install @eggl-js/expo-github-cache --save-devor
bun add @eggl-js/expo-github-cache -dTip
If you prefer to use the GitHub NPM registry, you can install the package directly from there:
npm install @robert27/expo-github-cache --registry=https://npm.pkg.github.comCreate a GitHub Personal Access Token with repo permissions and set it as an environment variable:
export GITHUB_TOKEN=your_github_token_hereAdd the build cache provider to your app.json or app.config.js:
{
"expo": {
"experiments": {
"remoteBuildCache": {
"provider": {
"plugin": "@eggl-js/expo-github-cache",
"options": {
"owner": "demo-org",
"repo": "demo-repo",
}
}
}
}
}
}Now when you run your Expo commands, the cache will automatically be used:
npx expo run:ios
npx expo run:androidThe plugin uses your project's fingerprint hash to create unique tags in GitHub Releases. Each build artifact is stored as a release asset with a tag like:
fingerprint.abc123def456.ios- iOS production buildfingerprint.abc123def456.dev-client.android- Android development client build
When you run a build command, the plugin:
- Calculates your project's current fingerprint
- Searches for a GitHub Release with the matching tag
- Downloads the cached build if found, or compiles and uploads if not
- Node.js 18 or higher
- GitHub repository with release permissions
- GitHub Personal Access Token with
reposcope - Expo project with fingerprinting enabled
| Variable | Required | Description |
|---|---|---|
GITHUB_TOKEN |
Yes | GitHub Personal Access Token with repo permissions |
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
This plugin extends the functionality of Expo's basic GitHub cache provider example. Here's when to use each:
Use the base example if:
- You want a simple, minimal implementation to understand the concepts
- You prefer to copy and customize the code directly in your project
- You need a starting point for building your own custom cache provider
Use this plugin if:
- You want a production-ready, installable package and want to keep your project clean
- You prefer npm/bun package management over copying files
- You want additional features like comprehensive error handling and logging
- You need a maintained solution with tests and CI/CD
Both implement the same Expo remote build cache provider interface, so they're functionally equivalent at the core level.
MIT