Metro Cache Key

Metro Cache Key is a simple cache key generation utility for the Metro bundler that creates MD5 hashes based on file contents. It provides a single function to generate deterministic hash keys from arrays of file paths, enabling efficient cache invalidation when source files change in Metro's JavaScript bundling pipeline.

Package Information

• Package Name: metro-cache-key
• Package Type: npm
• Language: JavaScript (with Flow type annotations)
• Installation: npm install metro-cache-key
• Node.js Version: >=20.19.4

Core Imports

CommonJS:

const { getCacheKey } = require("metro-cache-key");

Alternative CommonJS:

const metroCache = require("metro-cache-key");
const getCacheKey = metroCache.getCacheKey;

ESM (if using Node.js with type: "module"):

import { getCacheKey } from "metro-cache-key";

Basic Usage

const { getCacheKey } = require("metro-cache-key");

// Generate cache key from a single file
const cacheKey1 = getCacheKey(["/path/to/file.js"]);
console.log(cacheKey1); // "651e28171df9ff5d72a4115295dfce6b"

// Generate cache key from multiple files
const cacheKey2 = getCacheKey([
  "/path/to/file1.js",
  "/path/to/file2.js",
  "/path/to/config.json"
]);
console.log(cacheKey2); // "40457a98d325b546bed62a34c7d7cf96"

// Cache keys are deterministic - same files produce same key
const duplicateKey = getCacheKey(["/path/to/file.js"]);
console.log(cacheKey1 === duplicateKey); // true

Capabilities

Cache Key Generation

Generates an MD5 hash cache key from an array of file paths by reading file contents and combining them with MD5 hashing.

/**
 * Generates an MD5 hash cache key from an array of file paths
 * @param files - Array of file paths to generate cache key from
 * @returns MD5 hash in hexadecimal format
 */
function getCacheKey(files: Array<string>): string;

Parameters:

• files (Array<string>): Array of absolute file paths. Each file will be read synchronously and its contents included in the hash calculation.

Returns:

• string: MD5 hash in hexadecimal format (32 characters)

Behavior:

• Reads each file using fs.readFileSync()
• Combines file contents with null byte separators (\0)
• Uses Node.js crypto.createHash('md5') for hashing
• Returns final hash as hex string
• Deterministic: identical file contents always produce identical cache keys
• Order-sensitive: different file order produces different cache keys

Error Handling:

• Throws file system errors if files cannot be read (e.g., ENOENT: no such file or directory, EACCES: permission denied)
• Throws crypto errors if hashing fails (rare in normal operation)

Usage Examples:

const { getCacheKey } = require("metro-cache-key");

// Single file
const singleFileKey = getCacheKey(["/app/src/index.js"]);

// Multiple files (common Metro bundler usage)
const bundleKey = getCacheKey([
  "/app/src/index.js",
  "/app/src/components/App.js",
  "/app/package.json",
  "/app/metro.config.js"
]);

// Cache validation pattern
function isCacheValid(cacheKey, filePaths) {
  const currentKey = getCacheKey(filePaths);
  return currentKey === cacheKey;
}

Types

// Flow type annotations (internal - not exported)
type FilePath = string;
type CacheKey = string;

getCacheKey(files: Array<FilePath>): CacheKey;

Note: This package uses Flow type annotations internally but does not export TypeScript definitions. The types shown above are for reference only and represent the internal Flow types used in the source code.

Implementation Details

The function uses a reduction pattern to build the hash:

1. Creates an MD5 hash instance using crypto.createHash('md5')
2. For each file in the array:
   • Updates hash with null byte separator (\0)
   • Updates hash with file contents from fs.readFileSync(file)
3. Returns final hash as hexadecimal string using .digest('hex')

The null byte separator ensures that different files with concatenated contents don't produce hash collisions.

Metro Integration

This utility is designed specifically for Metro bundler's caching system:

• Build Cache: Generate keys for JavaScript bundles based on source files
• Transform Cache: Create keys for individual file transformations
• Dependency Cache: Hash dependency trees for incremental builds
• Configuration Cache: Include config files in cache key calculation

The deterministic nature ensures cache invalidation works correctly when source files change, while identical content always produces the same cache key for optimal cache hits.