Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MetroBridge
✓ import { MetroBridge } from 'metro-bridge'
✗ import MetroBridge from 'metro-bridge'
MetroBridge is a named export, not default. Common mistake for developers migrating from CJS.
CDPSession
✓ import { CDPSession } from 'metro-bridge'
✗ const { CDPSession } = require('metro-bridge')
Package is ESM-only since Node>=18. Using require() will fail with ERR_REQUIRE_ESM. Use import statement instead.
MetroDiscovery
✓ import { MetroDiscovery } from 'metro-bridge'
✗ import { MetroDiscovery } from 'metro-bridge/src/MetroDiscovery'
Do not import from internal paths; they are not part of the public API and may change without notice.
fetchTargets
✓ import { fetchTargets } from 'metro-bridge'
Standalone function; also accessible as a method on MetroDiscovery instance.
selectBestTarget
✓ import { selectBestTarget } from 'metro-bridge'
Returns the target with highest priority (Bridgeless > Hermes > standard).
scanMetroPorts
✓ import { scanMetroPorts } from 'metro-bridge'
Scans common Metro ports on localhost; returns array of port numbers.
supportsMultipleDebuggers
✓ import { supportsMultipleDebuggers } from 'metro-bridge'
Checks target capabilities. Use to decide if CDPMultiplexer is needed.
CDPMultiplexer
✓ import { CDPMultiplexer } from 'metro-bridge'
✗ import { CDPMultiplexer } from 'metro-bridge/multiplexer'
Only needed for React Native <0.85. On 0.85+, Metro supports native multi-session and multiplexer is unnecessary.
Shows both high-level MetroBridge and low-level CDPSession usage, including target discovery and evaluation.
import { MetroBridge } from 'metro-bridge';
import { MetroDiscovery, selectBestTarget, supportsMultipleDebuggers, CDPSession } from 'metro-bridge';
async function example() {
// High-level API: connect to Metro on port 8081
try {
const bridge = await MetroBridge.connect(8081);
const count = await bridge.evaluate<number>('globalThis.__itemCount');
console.log('Item count:', count);
await bridge.close();
} catch {
console.log('Metro not running, skipping');
}
// Low-level: discover targets and attach CDP session
const discovery = new MetroDiscovery(8081);
const targets = await discovery.discover();
if (targets.length === 0) {
console.log('No targets found');
return;
}
const target = selectBestTarget(targets);
const supportsMulti = supportsMultipleDebuggers(target);
console.log('Supports multiple debuggers:', supportsMulti);
const session = await CDPSession.connect(target);
const result = await session.send('Runtime.evaluate', {
expression: '1 + 1',
returnByValue: true,
});
console.log('Evaluation result:', result);
await session.close();
}
example().catch(console.error);
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/metro-bridge/build/index.js not supported.
metro-bridge is ESM-only; CommonJS require() is not supported.
fixChange const x = require('metro-bridge') to import { x } from 'metro-bridge' in your code, and ensure your project uses ESM ("type": "module" in package.json) or a bundler that handles ESM. TypeError: MetroBridge is not a constructor
Using default import instead of named import: import MetroBridge from 'metro-bridge'.
fixUse import { MetroBridge } from 'metro-bridge' with curly braces. Error: connect ECONNREFUSED ::1:8081
Metro bundler is not running on port 8081, or connection refused due to firewall or host mismatch.
fixEnsure Metro is running: npx react-native start. If using a different port, pass it to MetroBridge.connect(port). Also try using 127.0.0.1 instead of localhost if IPv6 issues occur.
TypeError: Cannot read properties of undefined (reading 'webSocketDebuggerUrl')
The target object passed to CDPSession.connect is missing the webSocketDebuggerUrl property, possibly due to an invalid target or an outdated Metro version.
fixVerify that the target is valid: use selectBestTarget() from fetched targets. Ensure Metro version >=0.70.0. If using a custom discovery, check that the target object has the webSocketDebuggerUrl field.
Audit
Dependencies
wsrequiredRequired for WebSocket communication with Metro's CDP targets.
chrome-launcheroptionalOptional dependency needed for openDevTools() to launch Chrome DevTools.
chromium-edge-launcheroptionalOptional dependency needed for openDevTools() to launch Edge DevTools.