{"id":11304,"library":"metro-cache-key","title":"Metro Cache Key Utility","description":"The `metro-cache-key` package is an internal utility within the Metro bundler ecosystem, primarily responsible for generating consistent and correct cache keys. These keys are crucial for optimizing build performance by enabling Metro to effectively cache various components, such as transformer outputs and Babel configurations, in React Native projects. The package is currently at version 0.84.3. As an integral part of the larger Metro monorepo, its release schedule is synchronized with Metro's development, typically involving frequent minor updates and occasional hotfixes. A key differentiator is its deep integration and specialized optimization for Metro's internal caching strategy, addressing complex factors like user-defined Babel configs to prevent stale caches and ensure build correctness.","status":"active","version":"0.84.3","language":"javascript","source_language":"en","source_url":"https://github.com/facebook/metro","tags":["javascript","typescript"],"install":[{"cmd":"npm install metro-cache-key","lang":"bash","label":"npm"},{"cmd":"yarn add metro-cache-key","lang":"bash","label":"yarn"},{"cmd":"pnpm add metro-cache-key","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` might work in some Node.js environments, Metro and its utilities are primarily developed with ESM in mind. Always prefer `import` for forward compatibility and proper type resolution.","wrong":"const createCacheKey = require('metro-cache-key');","symbol":"createCacheKey","correct":"import { createCacheKey } from 'metro-cache-key';"},{"note":"Import types separately using `import type` for clarity and to avoid runtime overhead. This package ships with TypeScript types.","symbol":"CacheKeyConfig","correct":"import type { CacheKeyConfig } from 'metro-cache-key';"},{"note":"This pattern imports all named exports into a single namespace object. It's less common than direct named imports but useful when exploring available exports or aggregating utilities.","wrong":"const CacheKey = require('metro-cache-key');","symbol":"* as CacheKey","correct":"import * as CacheKey from 'metro-cache-key';"}],"quickstart":{"code":"import { createCacheKey } from 'metro-cache-key';\nimport crypto from 'crypto';\n\n// Simulate a basic configuration object for which a cache key is needed\n// In a real Metro context, this config would be more complex and passed by Metro itself.\nconst projectConfig = {\n  root: '/path/to/my/project',\n  transformerPath: 'metro-react-native-babel-transformer',\n  resolverPath: 'metro-resolver',\n  babelConfig: {\n    presets: ['module:metro-react-native-babel-preset'],\n    plugins: ['react-native-reanimated/plugin'],\n  },\n  platform: 'ios',\n  dev: true,\n  // Other factors like Node.js version, Metro version, etc., might also be included\n  environmentHash: process.env.NODE_VERSION || 'unknown_node_version',\n};\n\n// This `generateSimpleCacheKey` function is illustrative. The actual `createCacheKey`\n// from the package would handle complex serialization and hashing internally.\nfunction generateSimpleCacheKey(config: any): string {\n  const configString = JSON.stringify(config, Object.keys(config).sort());\n  return crypto.createHash('md5').update(configString).digest('hex');\n}\n\n// Example usage, conceptually aligning with how `metro-cache-key` might be used\n// The actual `createCacheKey` from the package would be called directly.\nconst cacheKey = createCacheKey ? createCacheKey(projectConfig) : generateSimpleCacheKey(projectConfig);\nconsole.log(`Generated cache key: ${cacheKey}`);\n\n// If a critical input changes, the cache key should change, invalidating previous caches.\nconst anotherConfig = { ...projectConfig, dev: false };\nconst anotherCacheKey = createCacheKey ? createCacheKey(anotherConfig) : generateSimpleCacheKey(anotherConfig);\nconsole.log(`Another cache key (dev: false): ${anotherCacheKey}`);\n\nif (cacheKey === anotherCacheKey) {\n  console.warn('Warning: Cache keys should differ if configuration changes!');\n}\n","lang":"typescript","description":"This quickstart demonstrates how a cache key might be generated for a simulated Metro project configuration using a conceptual `createCacheKey` function, highlighting its role in identifying unique build contexts for effective caching."},"warnings":[{"fix":"Ensure your Node.js environment meets the minimum requirements: `^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0`. Upgrade Node.js if necessary.","message":"Version 0.84.0 introduced breaking changes by dropping support for older Node.js versions. Specifically, Node v21, v23, and LTS minors released before v20.19 are no longer supported.","severity":"breaking","affected_versions":">=0.84.0"},{"fix":"Always use the latest patch version available (e.g., 0.84.3) to ensure you have the correct TypeScript types. If facing type issues, try clearing your `node_modules` and reinstalling dependencies.","message":"Several recent versions (0.83.5 and 0.84.2) had issues with publishing TypeScript types, leading to temporary periods where types might have been missing or incorrect for these versions.","severity":"gotcha","affected_versions":"0.83.5, 0.84.2"},{"fix":"For most React Native developers, `metro-cache-key` is an indirect dependency managed by Metro. Avoid direct imports unless you are specifically working on Metro or a custom transformer/resolver.","message":"This package is an internal utility of the Metro bundler. Direct usage in application code is uncommon and may lead to unexpected behavior or reliance on unstable internal APIs. It's primarily intended for developers extending Metro itself.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"When extending Metro's caching mechanisms, ensure all relevant inputs that could affect the output of a build step are included in the cache key generation logic. Refer to Metro's source for how it constructs its own keys.","message":"Improper generation of cache keys (e.g., omitting relevant configuration factors) can lead to stale caches, where Metro uses outdated build artifacts, causing incorrect or unexpected application behavior.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update your Node.js installation to a compatible version as specified in the package's `engines` field.","cause":"Using an unsupported Node.js version with `metro-cache-key` (and by extension, Metro itself).","error":"Error: The current Node.js version is not supported. Please upgrade to Node.js ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0."},{"fix":"Ensure `metro-cache-key` is listed in your `package.json` and correctly installed. If using TypeScript, update to the latest patch version to mitigate issues with missing type definitions.","cause":"Attempting to import the module or its types when it's not correctly installed, or if TypeScript type declarations are missing/incorrect for the specific version you are using.","error":"Cannot find module 'metro-cache-key' or its corresponding type declarations."},{"fix":"Verify the exact named exports provided by the package. Consider using `import * as CacheKey from 'metro-cache-key'` to inspect available exports, or check the package's `index.d.ts` for type definitions.","cause":"Incorrectly importing a named export, or the assumed function name `createCacheKey` is different from the actual export.","error":"TypeError: createCacheKey is not a function"}],"ecosystem":"npm"}