Registry /
devops / metro-bundler-config-yarn-workspaces
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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
getMetroConfig
✓ const getMetroConfig = require('metro-bundler-config-yarn-workspaces');
✗ import getMetroConfig from 'metro-bundler-config-yarn-workspaces';
Metro configuration files (`metro.config.js`) are typically CommonJS modules, so `require` is the standard and expected import method. ESM imports are generally not supported for these configuration files.
Demonstrates how to integrate this package into a `metro.config.js` file for a React Native project within a Yarn Workspaces monorepo, configuring paths for module resolution and file watching.
const path = require('path');
const getMetroConfig = require('metro-bundler-config-yarn-workspaces');
// Determine the root of your monorepo. If metro.config.js is in 'apps/my-app/',
// then the workspace root is '../..' relative to this file.
const projectRoot = __dirname;
const workspaceRoot = path.resolve(projectRoot, '../..');
module.exports = getMetroConfig({
projectRoot,
workspaceRoot,
// Add any additional watch folders specific to your monorepo setup,
// for example, if you have a 'shared' packages directory.
watchFolders: [
path.resolve(workspaceRoot, 'packages'), // Example: if shared packages are in a 'packages' dir
path.resolve(workspaceRoot, 'node_modules') // Ensure hoisted node_modules are watched
],
// Optionally, customize resolver options if needed, e.g., for specific assets or extensions.
// resolver: {
// extraNodeModules: {
// 'react-native': path.resolve(projectRoot, 'node_modules/react-native')
// },
// assetExts: ['db', 'json', 'wasm', 'txt', 'jpg', 'png', 'ttf'],
// sourceExts: ['js', 'jsx', 'ts', 'tsx', 'json', 'mjs']
// }
});
Debug
Known issues
breakingUpgrading Metro or React Native versions can often introduce breaking changes to monorepo setups, especially concerning module resolution, symlink handling, and default configuration values. Older solutions for `blacklistRE` or `getProjectRoots` may be deprecated or require updates to newer Metro APIs like `exclusionList` and `watchFolders`.fixReview the official React Native and Metro documentation for each major upgrade. Update `metro.config.js` to use modern configuration options such as `watchFolders` and `resolver.nodeModulesPaths`, and ensure `exclusionList` is correctly applied. Consult monorepo setup guides specific to your React Native and Metro versions.
affects: >=0.59.0 of React Native / Metro
gotchaIncorrectly configured `watchFolders` or `resolver.nodeModulesPaths` can lead to Metro failing to find modules, particularly when dependencies are hoisted to the monorepo root or when shared packages are symlinked. Metro needs explicit instructions to scan directories outside the immediate project root.fixEnsure `watchFolders` includes the monorepo root, any directories containing shared workspaces (e.g., `packages/`), and the root `node_modules` directory. Explicitly set `resolver.nodeModulesPaths` to include both the app's local `node_modules` and the workspace root's `node_modules`.
affects: >=1.0.0
gotchaYarn's `nohoist` option can complicate Metro's module resolution by preventing certain packages from being hoisted to the root `node_modules`. While sometimes necessary for native modules, it can lead to package duplication and ambiguous resolution issues if not managed carefully.fixMinimize `nohoist` usage. If required, ensure the `metro.config.js` explicitly includes the paths to these non-hoisted `node_modules` directories in `watchFolders` and `resolver.nodeModulesPaths`. Verify that multiple versions of the same library are not being bundled, which can lead to runtime errors or increased bundle size.
affects: >=1.0.0
gotchaMetro often caches build artifacts and configurations. Changes to `metro.config.js` or underlying dependencies may not be picked up without clearing the cache, leading to seemingly inexplicable build errors or outdated bundles.fixAlways run Metro with the `--reset-cache` flag (e.g., `npx react-native start --reset-cache`) after making changes to your Metro configuration, adding/removing dependencies, or encountering unexpected bundling issues. This ensures Metro rebuilds its asset and module maps from scratch.
affects: >=1.0.0
deprecatedOlder Metro configurations might use `blacklistRE` for excluding files. This option has been superseded by `resolver.exclusionList`, which offers more robust and idiomatic pattern matching.fixUpdate your `metro.config.js` to use `resolver.exclusionList` instead of `blacklistRE`. This typically involves importing `exclusionList` from `metro-config/src/defaults/exclusionList` and merging it with your custom patterns.
affects: <0.59.0 (prior to React Native 0.59)
Errors
Common errors & fixes
error: bundling failed: Error: Unable to resolve module 'some-package' from 'path/to/file.js': The module 'some-package' could not be found from 'path/to/file.js'.
Metro cannot find a dependency due to incorrect `watchFolders` or `resolver.nodeModulesPaths` configuration, especially common in monorepos where modules are hoisted or symlinked.
fixEnsure your `metro.config.js` correctly defines `watchFolders` to include all relevant directories (monorepo root, shared packages, root `node_modules`) and `resolver.nodeModulesPaths` points to all `node_modules` locations Metro should check.
error: bundling failed: Error: Ambiguous resolution: module `react-native` is defined in multiple places: `node_modules/react-native/index.js`, `../../node_modules/react-native/index.js`
Multiple instances of the `react-native` package are being resolved, often due to a combination of local and hoisted dependencies in a monorepo, leading to conflict.
fixUse the `resolver.extraNodeModules` and `resolver.blacklistRE` (or `resolver.exclusionList`) options in `metro.config.js` to explicitly tell Metro which single instance of `react-native` to use, typically the one hoisted at the monorepo root.
PackageResolutionError: While trying to resolve module `@apollo/client` from file `App.tsx`, the package `/Users/user/monorepo/node_modules/@apollo/client/package.json` was successfully found. However, this package itself specifies a `main` module field that could not be resolved (`/Users/user/monorepo/node_modules/@apollo/client/main.cjs`). Indeed, none of these files exist: ...
Metro's resolver has trouble with package exports or specific module entry points (e.g., `.cjs` files) within a monorepo context, sometimes due to older Metro versions or misconfigurations.
fixEnsure your `metro.config.js` includes `cjs` in `resolver.sourceExts`. For newer Metro versions (0.75.1+), ensure `unstable_enablePackageExports` is enabled if using `package.json` `exports` field extensively. Check the specific package's `package.json` for its main entry points.
libc++abi.dylib: terminating with uncaught exception of type NSException *** Terminating app due to…exception 'NSInternalInconsistencyException', reason: 'Could not find the expected embedded asset Zocial.ttf.'
Native assets (like fonts or images) from shared packages or dependencies are not being correctly bundled or linked in the native project (iOS/Android), often because Metro isn't aware of their paths or `nohoist` issues.
fixVerify that `watchFolders` in `metro.config.js` includes all relevant asset directories. For native modules, ensure `nohoist` is correctly configured in `package.json` (if used), and check that Xcode/Gradle build phases are correctly linking assets from the expected `node_modules` locations, potentially requiring manual adjustments to native build scripts.
Audit
Dependencies
No dependency data recorded yet.