Registry / devops / metro-cache-key

metro-cache-key

JSON →
library0.84.3jsnpmunverified

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.

npm install metro-cache-key
INSTALL
IMPORT
SIG · METRO-CACHE-KEY
M
metro-cache-key
devopsjavascriptv0.84.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createCacheKey
import { createCacheKey } from 'metro-cache-key';
const createCacheKey = require('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
import * as CacheKey from 'metro-cache-key';
const CacheKey = require('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.

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!'); }
Debug
Known issues
breakingVersion 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.
affects: >=0.84.0
gotchaSeveral 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.
affects: 0.83.5, 0.84.2
gotchaThis 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.
affects: >=0.1.0
gotchaImproper 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.
affects: >=0.1.0
Errors
Common errors & fixes
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.
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.
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
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.
Upgrade
Version history
0.84.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources