0
# Metro Cache Key
1

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

4
## Package Information
5

6
- **Package Name**: metro-cache-key
7
- **Package Type**: npm
8
- **Language**: JavaScript (with Flow type annotations)
9
- **Installation**: `npm install metro-cache-key`
10
- **Node.js Version**: >=20.19.4
11

12
## Core Imports
13

14
CommonJS:
15

16
```javascript
17
const { getCacheKey } = require("metro-cache-key");
18
```
19

20
Alternative CommonJS:
21

22
```javascript
23
const metroCache = require("metro-cache-key");
24
const getCacheKey = metroCache.getCacheKey;
25
```
26

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

29
```javascript
30
import { getCacheKey } from "metro-cache-key";
31
```
32

33
## Basic Usage
34

35
```javascript
36
const { getCacheKey } = require("metro-cache-key");
37

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

42
// Generate cache key from multiple files
43
const cacheKey2 = getCacheKey([
44
  "/path/to/file1.js",
45
  "/path/to/file2.js",
46
  "/path/to/config.json"
47
]);
48
console.log(cacheKey2); // "40457a98d325b546bed62a34c7d7cf96"
49

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

55
## Capabilities
56

57
### Cache Key Generation
58

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

61
```javascript { .api }
62
/**
63
 * Generates an MD5 hash cache key from an array of file paths
64
 * @param files - Array of file paths to generate cache key from
65
 * @returns MD5 hash in hexadecimal format
66
 */
67
function getCacheKey(files: Array<string>): string;
68
```
69

70
**Parameters:**
71
- `files` (Array<string>): Array of absolute file paths. Each file will be read synchronously and its contents included in the hash calculation.
72

73
**Returns:**
74
- `string`: MD5 hash in hexadecimal format (32 characters)
75

76
**Behavior:**
77
- Reads each file using `fs.readFileSync()`
78
- Combines file contents with null byte separators (`\0`)
79
- Uses Node.js `crypto.createHash('md5')` for hashing
80
- Returns final hash as hex string
81
- Deterministic: identical file contents always produce identical cache keys
82
- Order-sensitive: different file order produces different cache keys
83

84
**Error Handling:**
85
- Throws file system errors if files cannot be read (e.g., `ENOENT: no such file or directory`, `EACCES: permission denied`)
86
- Throws crypto errors if hashing fails (rare in normal operation)
87

88
**Usage Examples:**
89

90
```javascript
91
const { getCacheKey } = require("metro-cache-key");
92

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

96
// Multiple files (common Metro bundler usage)
97
const bundleKey = getCacheKey([
98
  "/app/src/index.js",
99
  "/app/src/components/App.js",
100
  "/app/package.json",
101
  "/app/metro.config.js"
102
]);
103

104
// Cache validation pattern
105
function isCacheValid(cacheKey, filePaths) {
106
  const currentKey = getCacheKey(filePaths);
107
  return currentKey === cacheKey;
108
}
109
```
110

111
## Types
112

113
```javascript { .api }
114
// Flow type annotations (internal - not exported)
115
type FilePath = string;
116
type CacheKey = string;
117

118
getCacheKey(files: Array<FilePath>): CacheKey;
119
```
120

121
**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.
122

123
## Implementation Details
124

125
The function uses a reduction pattern to build the hash:
126

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

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

135
## Metro Integration
136

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

139
- **Build Cache**: Generate keys for JavaScript bundles based on source files
140
- **Transform Cache**: Create keys for individual file transformations
141
- **Dependency Cache**: Hash dependency trees for incremental builds
142
- **Configuration Cache**: Include config files in cache key calculation
143

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