EAS Build Cache Provider

Common errors

• EAS CLI encountered an unexpected error: Missing environment flag for update command.

  cause This error occurs when attempting to run `eas update` for an Expo SDK 55+ project without explicitly providing the `--environment` flag.
  fix Modify your `eas update` command to include `--environment <your-environment-name>`. For example: `eas update --branch main --environment production`.

• Error: Cannot find module 'eas-build-cache-provider' from 'your-project-path/node_modules/eas-cli/build/cache/CacheModule.js'

  cause The `eas-build-cache-provider` package was not correctly installed as a development dependency or is not accessible within the `node_modules` structure during the EAS build process.
  fix Ensure you have installed the package correctly by running `npm install --save-dev eas-build-cache-provider` or `yarn add --dev eas-build-cache-provider` in your project's root directory. Verify that `node_modules` is included in your build context.

• Error: EACCES: permission denied, open '/var/folders/.../eas-cli/cache/eas-build-cache.json'

  cause The EAS CLI or the build agent lacks the necessary write permissions to its cache directory, often encountered in restricted CI environments or due to incorrect local file permissions.
  fix Attempt to clear the EAS cache using `eas build:cache --clear`. On local machines, you might also try `rm -rf ~/.eas/` (macOS/Linux). For CI environments, confirm that the build user has appropriate read/write permissions for the `~/.eas/` directory or its equivalent temporary cache locations.

Warnings

• breaking Starting with EAS CLI v18.0.5, the `--environment` flag became a mandatory requirement for `eas update` commands when targeting Expo SDK version 55 or higher. Failing to include this flag will result in an error and prevent updates from being pushed.
  Fix: Ensure all `eas update` commands, especially in CI/CD pipelines, include `--environment <your-environment-name>` when your project uses Expo SDK 55 or newer (e.g., `eas update --branch production --environment production`).
• gotcha The `eas-build-cache-provider` is a backend plugin for EAS CLI, primarily configured through `app.json` or `app.config.js`. It is not intended for direct programmatic imports or usage within your application's JavaScript/TypeScript code. Attempting to import and use its symbols directly for application logic is a misapplication and will likely result in unexpected behavior or unnecessary bundle bloat.
  Fix: Do not import symbols from `eas-build-cache-provider` into your application code. Instead, enable the cache provider by setting the `buildCacheProvider` property to `'eas'` within the `experiments` section of your project's `app.json`.
• gotcha This package, being part of the `eas-cli` ecosystem, has a minimum Node.js engine requirement of `>=20.0.0`. Using an older Node.js version when running `eas build` or other EAS CLI commands that interact with this plugin may lead to compatibility issues or build failures.
  Fix: Ensure your Node.js environment is updated to version 20.0.0 or higher before executing EAS CLI commands that utilize this plugin.

Install

• npm install eas-build-cache-provider npm
• yarn add eas-build-cache-provider yarn
• pnpm add eas-build-cache-provider pnpm

Imports

• EasBuildCacheProvider
  wrong:

  const EasBuildCacheProvider = require('eas-build-cache-provider');

  correct:

  import EasBuildCacheProvider from 'eas-build-cache-provider';

  While this plugin is primarily configured via `app.json`, this represents the assumed default export of the provider implementation. It is mainly consumed internally by EAS CLI during the build process; direct programmatic instantiation by app developers is uncommon, but this would be the correct ESM import pattern if needed.
• BuildCacheProviderPlugin

  import type { BuildCacheProviderPlugin } from 'eas-build-cache-provider';

  This TypeScript type defines the interface expected for a build cache provider within the EAS ecosystem. It is relevant for developers who might be extending or deeply understanding the internal workings of EAS build plugins, rather than for typical application development.
• EasBuildCacheProviderConfig

  import type { EasBuildCacheProviderConfig } from 'eas-build-cache-provider';

  This TypeScript type represents the structure of the configuration object that the EAS build cache provider expects. This configuration is typically defined under the `experiments.buildCacheProvider` key in your Expo project's `app.json` or `app.config.js`.

Quickstart

Demonstrates how to enable the EAS build cache provider by configuring `app.json` and then running an `eas build` command to utilize the remote caching feature.

{
  "expo": {
    "name": "MyExpoApp",
    "slug": "my-expo-app",
    "version": "1.0.0",
    "orientation": "portrait",
    "icon": "./assets/icon.png",
    "userInterfaceStyle": "light",
    "splash": {
      "image": "./assets/splash.png",
      "resizeMode": "contain",
      "backgroundColor": "#ffffff"
    },
    "assetBundlePatterns": [
      "**/*"
    ],
    "ios": {
      "supportsTablet": true
    },
    "android": {
      "adaptiveIcon": {
        "foregroundImage": "./assets/adaptive-icon.png",
        "backgroundColor": "#ffffff"
      }
    },
    "web": {
      "favicon": "./assets/favicon.png"
    },
    "experiments": {
      "buildCacheProvider": "eas" // Enable the EAS remote build cache
    }
  }
}

// To use this configuration:
// 1. Install the package as a development dependency:
//    npm install --save-dev eas-build-cache-provider
// 2. Run an EAS build from your project directory:
//    eas build --platform android --profile development