{"id":15315,"library":"eas-build-cache-provider","title":"EAS Build Cache Provider","description":"The `eas-build-cache-provider` package serves as a specialized build cache provider plugin designed for seamless integration with the Expo CLI (specifically EAS Build). Its core functionality is to enable remote caching for build artifacts generated by EAS, which significantly accelerates subsequent build times by reusing cached components. Currently stable around version 18.5.0 (with recent updates up to 18.7.0), this package is typically configured declaratively within an Expo project's `app.json` or `app.config.js` file, making it a configuration-driven tool rather than one that requires direct programmatic imports in application code. The release cadence generally aligns with the broader `eas-cli` ecosystem, providing continuous feature enhancements and bug fixes. It's a critical component for optimizing CI/CD pipelines for Expo applications built with EAS.","status":"active","version":"18.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/expo/eas-cli","tags":["javascript","typescript"],"install":[{"cmd":"npm install eas-build-cache-provider","lang":"bash","label":"npm"},{"cmd":"yarn add eas-build-cache-provider","lang":"bash","label":"yarn"},{"cmd":"pnpm add eas-build-cache-provider","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a plugin specifically designed to extend the functionality of the Expo CLI's EAS Build system and cannot operate independently. It is conceptually a peer dependency.","package":"eas-cli","optional":false}],"imports":[{"note":"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.","wrong":"const EasBuildCacheProvider = require('eas-build-cache-provider');","symbol":"EasBuildCacheProvider","correct":"import EasBuildCacheProvider from 'eas-build-cache-provider';"},{"note":"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.","symbol":"BuildCacheProviderPlugin","correct":"import type { BuildCacheProviderPlugin } from 'eas-build-cache-provider';"},{"note":"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`.","symbol":"EasBuildCacheProviderConfig","correct":"import type { EasBuildCacheProviderConfig } from 'eas-build-cache-provider';"}],"quickstart":{"code":"{\n  \"expo\": {\n    \"name\": \"MyExpoApp\",\n    \"slug\": \"my-expo-app\",\n    \"version\": \"1.0.0\",\n    \"orientation\": \"portrait\",\n    \"icon\": \"./assets/icon.png\",\n    \"userInterfaceStyle\": \"light\",\n    \"splash\": {\n      \"image\": \"./assets/splash.png\",\n      \"resizeMode\": \"contain\",\n      \"backgroundColor\": \"#ffffff\"\n    },\n    \"assetBundlePatterns\": [\n      \"**/*\"\n    ],\n    \"ios\": {\n      \"supportsTablet\": true\n    },\n    \"android\": {\n      \"adaptiveIcon\": {\n        \"foregroundImage\": \"./assets/adaptive-icon.png\",\n        \"backgroundColor\": \"#ffffff\"\n      }\n    },\n    \"web\": {\n      \"favicon\": \"./assets/favicon.png\"\n    },\n    \"experiments\": {\n      \"buildCacheProvider\": \"eas\" // Enable the EAS remote build cache\n    }\n  }\n}\n\n// To use this configuration:\n// 1. Install the package as a development dependency:\n//    npm install --save-dev eas-build-cache-provider\n// 2. Run an EAS build from your project directory:\n//    eas build --platform android --profile development","lang":"typescript","description":"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."},"warnings":[{"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`).","message":"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.","severity":"breaking","affected_versions":">=18.0.5"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your Node.js environment is updated to version 20.0.0 or higher before executing EAS CLI commands that utilize this plugin.","message":"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.","severity":"gotcha","affected_versions":">=18.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Modify your `eas update` command to include `--environment <your-environment-name>`. For example: `eas update --branch main --environment production`.","cause":"This error occurs when attempting to run `eas update` for an Expo SDK 55+ project without explicitly providing the `--environment` flag.","error":"EAS CLI encountered an unexpected error: Missing environment flag for update command."},{"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.","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.","error":"Error: Cannot find module 'eas-build-cache-provider' from 'your-project-path/node_modules/eas-cli/build/cache/CacheModule.js'"},{"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.","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.","error":"Error: EACCES: permission denied, open '/var/folders/.../eas-cli/cache/eas-build-cache.json'"}],"ecosystem":"npm"}