Compiler cache for builds and Workflows

Builds on EAS now support saving and restoring compiler caches with ccache. ccache is a compiler cache that speeds up recompilation by caching the results of C/C++ compilation. The saved cache will store shared output between builds such as .o files, compilation results for native libraries used by React Native, Hermes, or other native modules, and more.

From our initial results on successful cache hits, we’ve seen up to 30% build speed increases on both Android and iOS builds and plan to improve it further.

The following environment variables control caching behavior:

• EAS_USE_CACHE: Enables saving and restoring cache on build jobs. By setting to 1, it will enable both saving and restoring the cache during a build job. By setting to 0, it will disable both saving and restoring the cache
• EAS_RESTORE_CACHE: Controls restoring the cache at the beginning of a build. Set to 1 to enable or 0 to disable.
• EAS_SAVE_CACHE: Controls whether to save the build cache at the end of a build. Set to 1 to enable or 0 to disable.

Prerequisites

• The remote compiler cache requires projects on SDK 53+ for Android and SDK 54+ for iOS.

Steps

1. Navigate to the project’s EAS environment variables settings page.
2. Create a new variable named EAS_USE_CACHE with a value of 1. Then select every environment, typically: production, preview, and development.
3. Kick off multiple builds. The first on will save the cache and subsequent builds will use that cache during their build process.

The cache key uses lock files to create a unique key based on your dependencies. When dependencies change, a new cache will be created while still allowing fallback to previous caches using a key prefix.

You’ll also see both save and restore-cache steps appear in your build job, along with performance stats on the hit rate of the cache.

Save and restore cache steps

Cache stats at the end of a build job

Setting the environment variables will automatically add the cache steps to your builds. You can also add this to your custom builds and workflows by setting the restore step before the build step and respective save step after.

Workflows

Use functions eas/restore_build_cache and eas/save_build_cache to apply ccache automatically.

- uses: eas/restore_build_cache
- uses: eas/build
- uses: eas/save_build_cache

Functions eas/restore_cache and eas/save_cache allow for using our service for other cache purposes. Users can define their own key pattern and file path. Here is an example of using them for ccache, equivalent to the functions above.

- uses: eas/restore_cache
  with:
    key: android-ccache-${{ hashFiles('package-lock.json') }}
    restore_keys: android
    path: /home/expo/.cache/ccache
- uses: eas/build
- uses: eas/save_cache
  with:
    key: android-ccache-${{ hashFiles('package-lock.json') }}
    path: /home/expo/.cache/ccache

Custom build

build:
  name: Build with ccache
  steps:
    - eas/checkout
    - eas/restore_build_cache
    - eas/build
    - eas/save_build_cache

Access restrictions provide cache isolation and security by creating logical boundaries between different Git branches or users. It is important for security of yours and your users to understand and leverage them when building your app.

When a build is run from GitHub, caches get scoped to the branch the build is running from. A build can restore caches created in:

• The current branch
• The default branch (main or master)

If a build doesn't restore a user-scoped cache, it will automatically fallback to restoring caches published from GitHub builds triggered on the default branch. This allows builds to benefit from caches created by trusted sources even when no user-scoped cache exists yet.

When a build is triggered from eas-cli, caches are scoped to the user running the build. These user-scoped caches allow for isolation so that modifications to the build and its cache are not unintentionally shared during development or between users.

When a single user-actor is shared between multiple people (such as when using access tokens or triggering builds from GitHub Actions), user-scoped cache rules still apply. This means that builds operating under that shared account will no longer have isolated caches and run the risk of sharing unintended artifacts. We recommend avoiding this by having designated jobs to only save clean caches, while the development builds only restore.

You can configure specific jobs to publish clean, new caches by disabling cache restoration and only saving the cache by leveraging our provided environment variables. These examples go over a few approaches to do so.

Disable restoring cache for production build profile

{
  "build": {
    "production": {
      "env": {
        "EAS_RESTORE_CACHE": "0",
        "EAS_SAVE_CACHE": "1"
      }
    },
    "preview": {
      "env": {
        "EAS_USE_CACHE": "1"
      }
    }
  }
}

Only save cache from designated jobs

To ensure only trusted sources publish cache, you can configure workflows to only save cache from specific jobs on the main branch:

jobs:
  build_production:
    type: build
    if: ${{ github.ref_name == 'main' }}
    env:
      EAS_RESTORE_CACHE: '0'
      EAS_SAVE_CACHE: '1'
    params:
      platform: android
      profile: production

Learn more about the usage and details of build cache on our docs.

We’d love to hear how build caches work for you. If you experience issues, please send an email to workflows@expo.io.