Skip to main content


@rnx-kit/metro-resolver-symlinks is a Metro resolver with proper support for symlinks. This is especially useful in monorepos, or repos using package managers that make heavy use of symlinks (such as pnpm).


yarn add @rnx-kit/metro-resolver-symlinks --dev

or if you're using npm

npm add --save-dev @rnx-kit/metro-resolver-symlinks


Import and assign the resolver to resolver.resolveRequest in your metro.config.js:

 const { makeMetroConfig } = require("@rnx-kit/metro-config");
+const MetroSymlinksResolver = require("@rnx-kit/metro-resolver-symlinks");

module.exports = makeMetroConfig({
resolver: {
+ resolveRequest: MetroSymlinksResolver(),


remapModule(moduleId: string) => stringA custom function for remapping additional modules.
experimental_retryResolvingFromDiskboolean[Experimental] Whether to retry module resolution on disk if not found in Haste map. This option is useful for scenarios where you want to reduce the number of watched files (and thus the initial time spent on crawling). Note that enabling this will likely be slower than having a warm cache.


remapModule allows additional remapping of modules. For instance, there is a remapImportPath utility that remaps requests of lib/**/*.js to src/**/*.ts. This is useful for packages that don't correctly export everything in their main JS file.

 const { makeMetroConfig } = require("@rnx-kit/metro-config");
const MetroSymlinksResolver = require("@rnx-kit/metro-resolver-symlinks");

module.exports = makeMetroConfig({
projectRoot: __dirname,
resolver: {
resolveRequest: MetroSymlinksResolver({
+ remapModule: MetroSymlinksResolver.remapImportPath({
+ test: (moduleId) => moduleId.startsWith("@rnx-kit/"),
+ extensions: [".ts", ".tsx"], // optional
+ mainFields: ["module", "main"], // optional
+ }),


When Metro releases a version with the ability to set a custom resolver for Haste requests, this way of remapping modules is preferable over @rnx-kit/babel-plugin-import-path-remapper. The Babel plugin mutates the AST and requires a second pass.