{"id":13162,"library":"expo-build-disk-cache","title":"Expo Build Disk Cache","description":"expo-build-disk-cache is a plugin for Expo CLI designed to significantly accelerate local development builds for Android and iOS by implementing a disk-based caching mechanism. Currently stable at version 0.7.4, this package provides near-instant launches for `npx expo run:android` and `npx expo run:ios` commands when a cached build is available, bypassing the time-consuming native compilation step. The project maintains an active release cadence, utilizing Changesets for versioning, with patches and minor feature updates occurring regularly. Its primary differentiator is the seamless integration into the Expo build process, offering a substantial productivity boost for developers by minimizing wait times during iterative development cycles, especially for larger projects.","status":"active","version":"0.7.4","language":"javascript","source_language":"en","source_url":"https://github.com/WookieFPV/expo-build-disk-cache","tags":["javascript","typescript"],"install":[{"cmd":"npm install expo-build-disk-cache","lang":"bash","label":"npm"},{"cmd":"yarn add expo-build-disk-cache","lang":"bash","label":"yarn"},{"cmd":"pnpm add expo-build-disk-cache","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Expo CLI functionality.","package":"@expo/cli","optional":false},{"reason":"Required peer dependency for Expo configuration utilities.","package":"@expo/config","optional":false}],"imports":[{"note":"Preferred for type-safe configuration in `app.config.ts` or ESM-enabled `app.config.js`.","wrong":"const buildDiskCacheProvider = require('expo-build-disk-cache');","symbol":"buildDiskCacheProvider","correct":"import { buildDiskCacheProvider } from 'expo-build-disk-cache';"},{"note":"Use this pattern if your `app.config.js` file is a CommonJS module. Expo CLI often handles `app.config.js` as CommonJS by default.","wrong":"import { buildDiskCacheProvider } from 'expo-build-disk-cache';","symbol":"buildDiskCacheProvider","correct":"const { buildDiskCacheProvider } = require('expo-build-disk-cache');"},{"note":"Used for type-checking the plugin configuration object in `app.config.ts`, ensuring correct option usage.","symbol":"Config","correct":"import type { Config } from 'expo-build-disk-cache';"}],"quickstart":{"code":"import { ExpoConfig } from '@expo/config';\nimport { buildDiskCacheProvider } from 'expo-build-disk-cache';\n\nconst config: ExpoConfig = {\n  name: 'MyExpoCacheApp',\n  slug: 'my-expo-cache-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  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  // For Expo SDK 54+:\n  buildCacheProvider: buildDiskCacheProvider({\n    cacheDir: process.env.EXPO_BUILD_CACHE_DIR ?? './.custom-expo-build-cache',\n    debug: process.env.EXPO_BUILD_CACHE_DEBUG === 'true',\n    maxAge: 7 * 24 * 60 * 60 * 1000 // Cache items expire after 7 days\n  })\n  // For Expo SDK 53, wrap in 'experiments':\n  // experiments: {\n  //   buildCacheProvider: buildDiskCacheProvider({\n  //     cacheDir: process.env.EXPO_BUILD_CACHE_DIR ?? './.custom-expo-build-cache',\n  //   }),\n  // },\n};\n\nexport default config;\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Move the `buildCacheProvider` configuration object directly under the root of your `app.config.js(on|ts)` file, removing the `experiments` wrapper.","message":"Configuration 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.","severity":"breaking","affected_versions":">=0.0.0 (when used with Expo SDK >= 54)"},{"fix":"Ensure your development environment uses Node.js v18.0.0 or newer. Consider using a version manager like `nvm` or `volta`.","message":"This package requires Node.js version 18.0.0 or higher. Using older Node.js versions will result in installation or runtime errors.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Upgrade `expo-build-disk-cache` to version `0.7.2` or higher to resolve stability issues with iOS Brownfield apps and symlinks.","message":"Earlier versions (prior to 0.7.2) could cause crashes in iOS Brownfield apps, particularly when symlinks were involved in the project structure.","severity":"gotcha","affected_versions":"<0.7.2"},{"fix":"Be 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)`.","message":"Configuration 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.","severity":"gotcha","affected_versions":">=0.5.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `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.","cause":"The plugin is not correctly installed or its name is misspelled in the `app.config.js(on|ts)` file.","error":"Error: Cannot find plugin 'expo-build-disk-cache' in app.config.js"},{"fix":"For 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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'plugin')"},{"fix":"Check 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.","cause":"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).","error":"Command failed with error: ENOENT: no such file or directory, stat '/path/to/project/.expo-build-cache'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}