Metro Cache Key Utility

Common errors

• 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.

  cause Using an unsupported Node.js version with `metro-cache-key` (and by extension, Metro itself).
  fix Update your Node.js installation to a compatible version as specified in the package's `engines` field.

• Cannot find module 'metro-cache-key' or its corresponding type declarations.

  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.
  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.

• TypeError: createCacheKey is not a function

  cause Incorrectly importing a named export, or the assumed function name `createCacheKey` is different from the actual export.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install metro-cache-key npm
• yarn add metro-cache-key yarn
• pnpm add metro-cache-key pnpm

Imports

• createCacheKey
  wrong:

  const createCacheKey = require('metro-cache-key');

  correct:

  import { createCacheKey } from 'metro-cache-key';

  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.
• CacheKeyConfig

  import type { CacheKeyConfig } from 'metro-cache-key';

  Import types separately using `import type` for clarity and to avoid runtime overhead. This package ships with TypeScript types.
• * as CacheKey
  wrong:

  const CacheKey = require('metro-cache-key');

  correct:

  import * as CacheKey from 'metro-cache-key';

  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.

Quickstart

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.

import { createCacheKey } from 'metro-cache-key';
import crypto from 'crypto';

// Simulate a basic configuration object for which a cache key is needed
// In a real Metro context, this config would be more complex and passed by Metro itself.
const projectConfig = {
  root: '/path/to/my/project',
  transformerPath: 'metro-react-native-babel-transformer',
  resolverPath: 'metro-resolver',
  babelConfig: {
    presets: ['module:metro-react-native-babel-preset'],
    plugins: ['react-native-reanimated/plugin'],
  },
  platform: 'ios',
  dev: true,
  // Other factors like Node.js version, Metro version, etc., might also be included
  environmentHash: process.env.NODE_VERSION || 'unknown_node_version',
};

// This `generateSimpleCacheKey` function is illustrative. The actual `createCacheKey`
// from the package would handle complex serialization and hashing internally.
function generateSimpleCacheKey(config: any): string {
  const configString = JSON.stringify(config, Object.keys(config).sort());
  return crypto.createHash('md5').update(configString).digest('hex');
}

// Example usage, conceptually aligning with how `metro-cache-key` might be used
// The actual `createCacheKey` from the package would be called directly.
const cacheKey = createCacheKey ? createCacheKey(projectConfig) : generateSimpleCacheKey(projectConfig);
console.log(`Generated cache key: ${cacheKey}`);

// If a critical input changes, the cache key should change, invalidating previous caches.
const anotherConfig = { ...projectConfig, dev: false };
const anotherCacheKey = createCacheKey ? createCacheKey(anotherConfig) : generateSimpleCacheKey(anotherConfig);
console.log(`Another cache key (dev: false): ${anotherCacheKey}`);

if (cacheKey === anotherCacheKey) {
  console.warn('Warning: Cache keys should differ if configuration changes!');
}