Registry / devops / metro-symlinked-deps

metro-symlinked-deps

library2.0.0jsnpmunverified

metro-symlinked-deps is a utility package designed to configure the Metro bundler, primarily used in React Native development, to overcome its inherent lack of support for symlinks. This deficiency often hinders local development workflows involving `yarn link` or `npm link` for shared dependencies by preventing Metro from resolving modules correctly across symlinked directories. Version 2.0.0 is the current stable release, which maintains compatibility with various `metro-config` versions by designating it as a peer dependency, thereby avoiding duplicate installations. The package provides a streamlined, automatic configuration function, `applyConfigForLinkedDependencies`, which intelligently manages Metro's `resolver.blacklistRE` and `watchFolders` settings. It addresses a long-standing issue in Metro (and its reliance on `jest-haste-map`) by allowing developers to integrate symlinked packages into their build process seamlessly. While not on a strict release cadence, it is updated as needed to address dependency changes and maintain its workaround effectiveness as long as Metro's native symlink issue persists.

devops

npm install metro-symlinked-deps

github ↗package ↗

INSTALL

IMPORT

SIG · METRO-SYMLINKED-DE

metro-symlinked-deps

devopsjavascriptv2.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

applyConfigForLinkedDependencies

✓ import { applyConfigForLinkedDependencies } from 'metro-symlinked-deps';

✗ import applyConfigForLinkedDependencies from 'metro-symlinked-deps';

This is the primary utility function for automatically applying symlink-aware configurations. It is exported as a named export, not a default export.

applyConfigForLinkedDependencies

✓ const { applyConfigForLinkedDependencies } = require('metro-symlinked-deps');

✗ const applyConfigForLinkedDependencies = require('metro-symlinked-deps');

The CommonJS `require` pattern for Node.js environments, typically used in `metro.config.js` files. Direct `require('pkg')` would return the entire module object.

Default export (non-existent)

✓ /* No default export is provided by this package. */

✗ import MetroSymlinkedDeps from 'metro-symlinked-deps';

Attempting to import a default export from 'metro-symlinked-deps' will result in an `undefined` value or a runtime error, as the package only provides named exports.

This example demonstrates how to integrate `metro-symlinked-deps` into your `metro.config.js` to enable symlink support. It automatically applies the necessary configurations, explicitly sets the project root for robustness, and includes common options like blacklisting modules and adding watch folders.

const { applyConfigForLinkedDependencies } = require('metro-symlinked-deps'); const { getDefaultConfig } = require('metro-config'); module.exports = (async () => { const defaultConfig = await getDefaultConfig(); return applyConfigForLinkedDependencies( { ...defaultConfig, // Add any custom Metro configuration here that you need to merge transformer: { babelTransformerPath: require.resolve('react-native-babel-transformer'), }, resolver: { ...defaultConfig.resolver, extraNodeModules: { // Example for a specific linked module if needed 'some-linked-module': __dirname + '/../some-linked-module', }, }, }, { projectRoot: __dirname, // Explicitly provide the project root blacklistLinkedModules: ['react-native'], // Blacklist common collision source additionalWatchFolders: [ // Add paths to any top-level linked packages here if not automatically detected __dirname + '/../path-to-your-linked-package-root' ] }, ); })();

Debug

Known issues

gotchaMetro bundler fundamentally lacks native symlink support, which is the underlying problem this package addresses. Misconfigurations or incomplete application of this workaround can lead to issues that mimic core Metro problems like 'Module not found' or incorrect module resolution.

fix

Ensure `metro-symlinked-deps` is correctly applied in your `metro.config.js`. Always clear the Metro cache (`npx react-native start --reset-cache`) after making configuration changes or linking new dependencies.

affects: >=1.0.0

gotchaFailure to explicitly provide the `projectRoot` option in `applyConfigForLinkedDependencies` can lead to incorrect detection of the project's root, causing linked dependencies or watch folders to be missed or resolved incorrectly.

fix

Always specify the `projectRoot` option for robustness, typically using `__dirname` within your `metro.config.js`: `{ projectRoot: __dirname }`.

affects: >=1.0.0

gotchaNaming collisions can occur, especially with common packages like `react-native` if they are included as a `devDependency` in a linked package. This often results in runtime errors such as 'Invariant Violation: ModuleAppRegistry is not a registered callable module'.

fix

Use the `blacklistLinkedModules` option to explicitly ignore problematic modules, e.g., `{ blacklistLinkedModules: ['react-native'] }`. Remember to reset the Metro cache (`npx react-native start --reset-cache`) after applying these changes.

affects: >=1.0.0

breakingSince version 2.0.0, `metro-config` transitioned from a direct dependency to a peer dependency. This change requires `metro-config` to be explicitly installed as a top-level dependency in your project's `package.json` for `metro-symlinked-deps` to function correctly.

fix

Add `metro-config` to your project's `devDependencies` (or `dependencies`) and ensure it's installed. For example: `yarn add metro-config` or `npm install metro-config`.

affects: >=2.0.0

Errors

Common errors & fixes

Unable to resolve module `your-linked-module` from `path/to/project`

Metro's resolver is not correctly configured to find the symlinked module, indicating the workaround might not be fully effective or the cache is stale.

fix

Verify that `metro-symlinked-deps` is correctly applied in your `metro.config.js`. Ensure `projectRoot` and `additionalWatchFolders` are accurately configured to include your linked packages. Always run `npx react-native start --reset-cache` after making changes to your configuration or linking new dependencies.

Error: Invariant Violation: ModuleAppRegistry is not a registered callable module (calling runApplication)

This error frequently arises from bundling multiple instances of `react-native`, typically when a linked dependency also includes `react-native` in its `node_modules`.

fix

Add `react-native` to the `blacklistLinkedModules` option in your `metro-symlinked-deps` configuration within `metro.config.js`: `{ blacklistLinkedModules: ['react-native'] }`. Subsequently, clear the Metro cache using `npx react-native start --reset-cache`.

ReferenceError: require is not defined (or similar errors with import/export in metro.config.js)

The `metro.config.js` file is typically executed in a CommonJS environment by Node.js. Using ES module `import`/`export` syntax directly without proper setup will lead to errors.

fix

Ensure your `metro.config.js` exclusively uses CommonJS `require()` and `module.exports` syntax, as demonstrated in the package's examples. If you intend to use ESM, your project's Node.js environment and Metro's configuration would need specific, advanced setup (e.g., setting `"type": "module"` in `package.json` and ensuring compatibility).

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

metro-configrequiredRequired by Metro projects for configuration merging; specified as a peer dependency to ensure compatibility across different Metro versions.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/alexbrazier/metro-symlinked-deps ↗

packagehttps://www.npmjs.com/package/metro-symlinked-deps ↗