fix(metro-config): fix assets outside of project root not rendering

.changeset/busy-ads-rescue.md

@@ -0,0 +1,20 @@
+---
+"@rnx-kit/metro-config": patch
+"@rnx-kit/metro-service": patch
+---
+
+Fixed assets outside of project root not rendering. This breaks release builds
+so it must be manually enabled in `metro.config.js`:
+
+```diff
+diff --git a/metro.config.js b/metro.config.js
+index 000000000..000000000 100644
+--- a/metro.config.js
++++ b/metro.config.js
+@@ -34,4 +34,5 @@ module.exports = makeMetroConfig({
+     blacklistRE: blockList,
+     blockList,
+   },
++  unstable_allowAssetsOutsideProjectRoot: true,
+ });
+```

packages/metro-config/src/assetPlugins/escapeAssetURLs.js

@@ -0,0 +1,46 @@
+/**
+ * @typedef {import("metro").AssetData} AssetData;
+ */
+
+/**
+ * @param {string} str
+ * @param {string} searchValue
+ * @param {string} replaceValue
+ * @returns {string}
+ */
+function replaceString(str, searchValue, replaceValue) {
+  return str.startsWith("/assets/")
+    ? str.replaceAll(searchValue, replaceValue)
+    : str;
+}
+
+/**
+ * Metro doesn't support assets in a monorepo setup. When the app requests
+ * assets at URLs such as `/assets/../../../node_modules/react-native/<...>`,
+ * the URL will be resolved to `/node_modules/react-native/<...>` and Metro will
+ * fail to resolve them. The workaround is to replace `..` with something else
+ * so the URL doesn't collapse when resolved, then restore them in
+ * `server.rewriteRequestUrl`.
+ *
+ * For more details, see https://github.com/facebook/metro/issues/290.
+ *
+ * @param {import("type-fest").Writable<AssetData>} assetData
+ * @returns {AssetData}
+ */
+function assetPlugin(assetData) {
+  const url = assetData.httpServerLocation;
+  assetData.httpServerLocation = replaceString(url, "../", "@@/");
+  return assetData;
+}
+
+/**
+ * Restores `..` in asset URLs.
+ * @param {string} url
+ * @returns {string}
+ */
+function restoreAssetURL(url) {
+  return replaceString(url, "@@/", "../");
+}
+
+module.exports = assetPlugin;
+module.exports.restoreAssetURL = restoreAssetURL;

packages/metro-config/src/assetPlugins/rewriteAssetURLs.js

@@ -0,0 +1,30 @@
+/**
+ * @typedef {import("metro").AssetData} AssetData;
+ */
+
+/**
+ * Metro doesn't support assets in a monorepo setup. When the app requests
+ * assets at URLs such as `/assets/../../../node_modules/react-native/<...>`,
+ * the URL will be resolved to `/node_modules/react-native/<...>` and Metro will
+ * fail to resolve them.
+ *
+ * In 0.67, they introduced a query parameter, `unstable_path`, specifically to
+ * handle such cases. However, this isn't properly fleshed out and only works in
+ * server mode. Bundling with this plugin may cause issues with asset paths.
+ *
+ * For more details, see https://github.com/facebook/metro/issues/290.
+ *
+ * @param {import("type-fest").Writable<AssetData>} assetData
+ * @returns {AssetData}
+ */
+module.exports = function (assetData) {
+  const prefix = "/assets/../";
+  const url = assetData.httpServerLocation;
+  if (url.startsWith(prefix)) {
+    assetData.httpServerLocation = url.replace(
+      prefix,
+      "/assets?unstable_path=../"
+    );
+  }
+  return assetData;
+};

packages/metro-config/src/index.js

@@ -11,7 +11,10 @@ const { applyExpoWorkarounds, isExpoConfig } = require("./expoConfig");
 
 /**
  * @typedef {import("metro-config").MetroConfig} MetroConfig;
- * @typedef {MetroConfig & { platform?: string; }} InputConfig;
+ * @typedef {MetroConfig & {
+ *   platform?: string;
+ *   unstable_allowAssetsOutsideProjectRoot?: boolean;
+ * }} InputConfig;
  */
 
 /** Packages that must be resolved to one specific copy. */
@@ -280,6 +283,53 @@ function exclusionList(additionalExclusions = [], projectRoot = process.cwd()) {
   ];
 }
 
+/**
+ * @param {string} projectRoot
+ * @param {InputConfig} inputConfig
+ * @returns {MetroConfig}
+ */
+function additionalConfig(projectRoot, inputConfig) {
+  const blockList = exclusionList([], projectRoot);
+
+  /** @type {import("type-fest").WritableDeep<MetroConfig["transformer"]>} */
+  const transformer = {
+    getTransformOptions: async () => ({
+      transform: {
+        experimentalImportSupport: false,
+        inlineRequires: false,
+      },
+    }),
+  };
+
+  /** @type {import("type-fest").Writable<MetroConfig>} */
+  const config = {
+    resolver: {
+      resolverMainFields: ["react-native", "browser", "main"],
+      blacklistRE: blockList, // For Metro < 0.60
+      blockList, // For Metro >= 0.60
+    },
+    transformer,
+    watchFolders: inputConfig.watchFolders ?? defaultWatchFolders(),
+  };
+
+  if (inputConfig.unstable_allowAssetsOutsideProjectRoot) {
+    // We currently cannot enable this by default because it affects the
+    // structure of the assets folder, breaking release builds.
+    transformer.assetPlugins = [
+      require.resolve("./assetPlugins/rewriteAssetURLs.js"),
+    ];
+  } else {
+    const { restoreAssetURL } = require("./assetPlugins/escapeAssetURLs.js");
+    config.server = { rewriteRequestUrl: restoreAssetURL };
+
+    transformer.assetPlugins = [
+      require.resolve("./assetPlugins/escapeAssetURLs.js"),
+    ];
+  }
+
+  return config;
+}
+
 module.exports = {
   defaultWatchFolders,
   excludeExtraCopiesOf,
@@ -296,36 +346,16 @@ module.exports = {
     const projectRoot = inputConfig.projectRoot || process.cwd();
 
     const { mergeConfig } = requireModuleFromMetro("metro-config", projectRoot);
-    const { enhanceMiddleware } = require("./assetPluginForMonorepos");
     const { getDefaultConfig } = require("./defaultConfig");
 
-    const blockList = exclusionList([], projectRoot);
     const customBlockList =
       inputConfig.resolver &&
       (inputConfig.resolver.blockList || inputConfig.resolver.blacklistRE);
 
     /** @type {MetroConfig[]} */
     const [defaultConfig, ...configs] = [
       ...getDefaultConfig(projectRoot, platform),
-      {
-        resolver: {
-          resolverMainFields: ["react-native", "browser", "main"],
-          blacklistRE: blockList, // For Metro < 0.60
-          blockList, // For Metro >= 0.60
-        },
-        server: {
-          enhanceMiddleware,
-        },
-        transformer: {
-          getTransformOptions: async () => ({
-            transform: {
-              experimentalImportSupport: false,
-              inlineRequires: false,
-            },
-          }),
-        },
-        watchFolders: inputConfig.watchFolders ?? defaultWatchFolders(),
-      },
+      additionalConfig(projectRoot, inputConfig),
       {
         ...inputConfig,
         resolver: {

packages/metro-config/test/assetPlugins/escapeAssetURLs.test.ts

@@ -0,0 +1,32 @@
+import type { AssetData } from "metro";
+import { equal } from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  default as escapeAssetURL,
+  restoreAssetURL,
+} from "../../src/assetPlugins/escapeAssetURLs.js";
+
+describe("assetPlugins/escapeRelativePaths", () => {
+  const cases = [
+    ["/assets/./node_modules", "/assets/./node_modules"],
+    ["/assets/../node_modules", "/assets/@@/node_modules"],
+    ["/assets/../../node_modules", "/assets/@@/@@/node_modules"],
+    [
+      "/assets/node_modules/../../react-native",
+      "/assets/node_modules/@@/@@/react-native",
+    ],
+  ] as const;
+
+  it("escapes `..` in URLs", () => {
+    for (const [input, output] of cases) {
+      const assetData = { httpServerLocation: input } as AssetData;
+      equal(escapeAssetURL(assetData).httpServerLocation, output);
+    }
+  });
+
+  it("unescapes `..` in URLs", () => {
+    for (const [output, input] of cases) {
+      equal(restoreAssetURL(input), output);
+    }
+  });
+});

packages/metro-config/test/assetPlugins/rewriteAssetURLs.test.ts

@@ -0,0 +1,27 @@
+import type { AssetData } from "metro";
+import { deepEqual } from "node:assert/strict";
+import { describe, it } from "node:test";
+import rewriteRequest from "../../src/assetPlugins/rewriteAssetURLs.js";
+
+describe("assetPlugins/rewriteRequestWithQueryParam", () => {
+  const cases = [
+    ["/assets/./node_modules", "/assets/./node_modules"],
+    ["/assets/../node_modules", "/assets?unstable_path=../node_modules"],
+    ["/assets/../../node_modules", "/assets?unstable_path=../../node_modules"],
+    [
+      "/assets/node_modules/../../react-native",
+      "/assets/node_modules/../../react-native",
+    ],
+    [
+      "/assets/local/path/with/nested/assets/../../react-native",
+      "/assets/local/path/with/nested/assets/../../react-native",
+    ],
+  ] as const;
+
+  it("rewrites request URLs with relative paths", () => {
+    for (const [input, output] of cases) {
+      const assetData = { httpServerLocation: input } as AssetData;
+      deepEqual(rewriteRequest(assetData), { httpServerLocation: output });
+    }
+  });
+});