Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
buildDiskCacheProvider
✓ import { buildDiskCacheProvider } from 'expo-build-disk-cache';
✗ const buildDiskCacheProvider = require('expo-build-disk-cache');
Preferred for type-safe configuration in `app.config.ts` or ESM-enabled `app.config.js`.
buildDiskCacheProvider
✓ const { buildDiskCacheProvider } = require('expo-build-disk-cache');
✗ import { buildDiskCacheProvider } from 'expo-build-disk-cache';
Use this pattern if your `app.config.js` file is a CommonJS module. Expo CLI often handles `app.config.js` as CommonJS by default.
Config
✓ import type { Config } from 'expo-build-disk-cache';
Used for type-checking the plugin configuration object in `app.config.ts`, ensuring correct option usage.
This quickstart demonstrates how to configure `expo-build-disk-cache` in your `app.config.ts` (or `app.config.js`) file, using the `buildDiskCacheProvider` helper for type-safe setup and showing common configuration options like `cacheDir`, `debug`, and `maxAge`, with environment variable fallbacks.
import { ExpoConfig } from '@expo/config';
import { buildDiskCacheProvider } from 'expo-build-disk-cache';
const config: ExpoConfig = {
name: 'MyExpoCacheApp',
slug: 'my-expo-cache-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',
},
// For Expo SDK 54+:
buildCacheProvider: buildDiskCacheProvider({
cacheDir: process.env.EXPO_BUILD_CACHE_DIR ?? './.custom-expo-build-cache',
debug: process.env.EXPO_BUILD_CACHE_DEBUG === 'true',
maxAge: 7 * 24 * 60 * 60 * 1000 // Cache items expire after 7 days
})
// For Expo SDK 53, wrap in 'experiments':
// experiments: {
// buildCacheProvider: buildDiskCacheProvider({
// cacheDir: process.env.EXPO_BUILD_CACHE_DIR ?? './.custom-expo-build-cache',
// }),
// },
};
export default config;
Debug
Known issues
breakingConfiguration for `buildCacheProvider` moved from within the `experiments` block to the root level of `app.config.js(on|ts)` for Expo SDK 54 and newer. Projects upgrading from SDK 53 or earlier must update their configuration.fixMove the `buildCacheProvider` configuration object directly under the root of your `app.config.js(on|ts)` file, removing the `experiments` wrapper.
affects: >=0.0.0 (when used with Expo SDK >= 54)
gotchaThis package requires Node.js version 18.0.0 or higher. Using older Node.js versions will result in installation or runtime errors.fixEnsure your development environment uses Node.js v18.0.0 or newer. Consider using a version manager like `nvm` or `volta`.
affects: >=0.0.0
gotchaEarlier versions (prior to 0.7.2) could cause crashes in iOS Brownfield apps, particularly when symlinks were involved in the project structure.fixUpgrade `expo-build-disk-cache` to version `0.7.2` or higher to resolve stability issues with iOS Brownfield apps and symlinks.
affects: <0.7.2
gotchaConfiguration options can be overridden by environment variables (e.g., `EXPO_BUILD_CACHE_DIR`, `EXPO_BUILD_CACHE_DEBUG`), which can lead to unexpected behavior if not accounted for.fixBe aware of environment variable precedence. When debugging configuration issues, check active environment variables that might be overriding settings in your `app.config.js(on|ts)`.
affects: >=0.5.0
Errors
Common errors & fixes
Error: Cannot find plugin 'expo-build-disk-cache' in app.config.js
The plugin is not correctly installed or its name is misspelled in the `app.config.js(on|ts)` file.
fixEnsure `npm install --save-dev expo-build-disk-cache` has been run and the plugin name is correctly specified as `"expo-build-disk-cache"` in your `buildCacheProvider` configuration.
TypeError: Cannot read properties of undefined (reading 'plugin')
The `buildCacheProvider` object in `app.config.js(on|ts)` is incorrectly structured or placed within the wrong configuration key, especially when migrating Expo SDK versions.
fixFor Expo SDK 54+, ensure `buildCacheProvider` is a direct root property of your config object. For SDK 53, it must be nested under `experiments.buildCacheProvider`. Verify the structure matches the documentation for your specific Expo SDK version.
Command failed with error: ENOENT: no such file or directory, stat '/path/to/project/.expo-build-cache'
This error can occur during build processes if there are file system access issues, insufficient permissions, or specific project configurations involving symlinks (especially on iOS).
fixCheck file permissions for the cache directory (`.expo-build-cache` by default or your custom `cacheDir`). If on iOS Brownfield with symlinks, ensure you are using `expo-build-disk-cache` version `0.7.2` or newer.
Audit
Dependencies
@expo/clirequiredRequired peer dependency for Expo CLI functionality.
@expo/configrequiredRequired peer dependency for Expo configuration utilities.