Use asset catalog for iOS images (#30129)

Summary:
Use an asset catalog for images on iOS. At build time, `react-native-xcode.sh` has the bundler emit packager image assets into a staging asset catalog (`--asset-catalog-dest`, already in `react-native/community-cli-plugin`), compiles it with `actool` into an `RNAssets.bundle` inside the app, and the native image loader resolves images by name from that bundle's `Assets.car` with `[UIImage imageNamed:inBundle:]` instead of reading loose files.

Properties worth calling out:
- **One opt-in switch, no project changes.** The feature is gated on the `RCTUseAssetCatalog` key in the app's Info.plist, and that key is the single source of truth: the native loader reads it (a build-time constant, read once), and `react-native-xcode.sh` reads the same key to decide whether to bundle images into the catalog — so the build and the runtime cannot disagree on where image assets live. Because the script owns the catalog end to end (staged in derived files, compiled into the app's resources next to `main.jsbundle`), **migration is adding one Info.plist key** — no `.xcassets` to create, no build-phase or project changes.
- **No fallback.** The catalog path is a single lookup with no filesystem fallback — a mis-bundled asset logs an `RCTLogError` (instead of silently rendering nothing) rather than adding an `fs` stat to the hot path.
- **Parity with the CLI, OTA-safe.** The native side resolves a catalog name only for what the CLI actually emits into the catalog: png/jpg/jpeg under main-bundle `assets/…` (mirroring `isCatalogAsset`). Everything else — gif/webp packager assets, `.bundle` sub-bundles, OTA assets outside the main bundle — falls through to the existing loader. (This also adds `jpeg` to `RCTIsImageAssetsPath`, which previously listed only `png`/`jpg` — an oversight, since `.jpeg` is the same kind of bundled image; it is now treated like `png`/`jpg` regardless of the catalog.)
- **No interference with Xcode's own asset pipeline.** The app's `Images.xcassets`, asset symbol generation (`UIImage(resource:)`), and `CompileAssetCatalog` are untouched: the RN catalog never enters the Xcode project, so there are no build-phase ordering constraints and nothing to disable.

## Changelog:

[iOS] [Added] - Use asset catalog for ios images

## Performance

**What was measured:** the time to *resolve* an asset to a `UIImage` inside `RCTImageFromLocalAssetURL` — a compiled-catalog name lookup vs. the legacy `imageNamed:` search + `imageWithContentsOfFile:` on loose files. Decode is deferred in both paths (and costs the same), so this is resolve latency, not end-to-end render time. It matters because `RCTLocalAssetImageLoader` loads local assets synchronously to avoid flicker, so this time sits on the critical path once per distinct image. Setup: RNTester, Release, new arch, iOS simulator, first load of each distinct image (UIKit caches repeats — repeat loads are ~10 µs in both builds).

Raw per-load numbers (final implementation, `RNAssets.bundle`), in load order:

| # | image | catalog (µs) | filesystem (µs) |
|---|---|---:|---:|
| 1 | `searchicon` ¹ | 1,081 | 4,497 |
| 2 | `bottomnavcomponentsicondark` | 320 | 710 |
| 3 | `bottomnavplaygroundsiconlight` | 147 | 422 |
| 4 | `bottomnavapisiconlight` | 29 | 352 |
| 5 | `bottomnavcomponentsiconlight` | 320 | 1,410 |
| 6 | `uie_thumb_normal` | 67 | 667 |
| 7 | `uie_thumb_selected` | 32 | 468 |
| 8 | `uie_comment_normal` | 26 | 454 |
| 9 | `uie_comment_highlighted` | 31 | 671 |
| 10 | `verylargeimage` ² | 30 | 1,855 |
| 11 | `alphahotdog` | 171 | 592 |

¹ First load in each build pays one-time costs: mapping `Assets.car` on the catalog side, ImageIO/framework warm-up + first disk touch on the filesystem side.
² Resolve only — the large image's decode cost is unchanged, so its end-to-end win is much smaller than this row suggests.

Every image is faster from the catalog: median 67 µs vs 667 µs (**10×**; an earlier run of the same benchmark measured 47 µs vs 719 µs, ~15× — run-to-run variance, same order either way). The mechanism: the catalog is a single memory-mapped, indexed archive (one name lookup, no per-image syscalls), while the loose-file path does an `imageNamed:` search over several filename permutations plus a per-image file open.

The URL→catalog-name derivation on the native side is a single character pass with no regex; benchmarked against a straightforward regex-based implementation of the same transform it measures 4.9 µs vs 11.0 µs per call (2.2×, Debug build, including the shared URL→bundle-path resolution both share), so the name mapping is a negligible part of the lookup.

**App thinning:** verified that App Store slicing thins the `Assets.car` inside `RNAssets.bundle` exactly like the app's own catalog. Test: a fixture app with a 1x/2x/3x imageset in both its main `Images.xcassets` and an actool-compiled `RNAssets.bundle`, archived and exported with `thinning` for a 3x device — both cars were sliced to 3x-only. So unused scales are stripped per device (unlike today's loose packager files, which ship every scale to every device).

## Migration

To opt an app in, add to its `Info.plist`:

```xml
<key>RCTUseAssetCatalog</key>
<true/>
```

That's the entire migration — no `.xcassets` to create, no build-phase or project changes. Notes:
- **Do a clean build after changing the key.** Incremental builds don't remove image assets a previous build placed with the other setting (unused, but dead weight in local builds; archives are unaffected).
- The key must be a literal value in the app's source Info.plist: the build script reads it with PlistBuddy (accepting the same value forms the runtime `boolValue` check accepts), so build-setting substitution or fully generated Info.plists (`GENERATE_INFOPLIST_FILE`) aren't seen by the script and stay on the legacy path. If bundling happens outside `react-native-xcode.sh` (custom CI calling `react-native bundle` directly) while the key is enabled, the native side detects the missing `RNAssets.bundle` and logs an actionable error instead of silently rendering nothing.
- Incomplete but valid scale sets degrade gracefully: an imageset with, say, only a `2x` (no `3x`) is kept for a 3x device by App Store slicing and used at runtime — verified with a thinned export. Only a *non-integer*-only asset (e.g. an Android-density `1.5x` with no `1x`/`2x`/`3x` variant, which iOS asset catalogs cannot represent) is unsupported: `actool` drops it with an `Unknown scale value` warning in the build log and the runtime logs an error. That's a rare antipattern; a `community-cli-plugin` follow-up will turn it into a clear build-time error at the source (it has the scale and asset path), rather than this repo re-parsing actool output.
- OTA updates keep working: assets delivered outside the main bundle never resolve to the catalog and use the regular loader.
- Docs follow-up: a section on the website's Images page (`react-native-website`) and the one-line opt-in in `react-native-community/template` will be separate PRs, timed with the release that ships this.

Pull Request resolved: #30129

Test Plan:
RNTester and `private/helloworld` both opt in (`RCTUseAssetCatalog=YES` in their Info.plists — the only change an app needs), so CI covers the catalog path on both app shapes. The new-project template lives in `react-native-community/template` and will get the same one-line opt-in in a follow-up PR there. To test locally with RNTester:

1. In Xcode, edit the RNTester scheme → set Build Configuration to Release.
2. Build & run. Local images render, served from `RNAssets.bundle/Assets.car`; the app contains no loose packager png/jpg files.

Unit coverage in `RCTURLUtilsTests` (`testAssetCatalogNameForURL`), asserting the identifiers the CLI generates: scale-suffix stripping (including non-integer `1.5x`), folder encoding, illegal-char removal, jpeg vs. non-catalog types (gif), out-of-project-root assets, query strings, non-packager paths, and nil.

Mac Catalyst: verified end-to-end by building rn-tester as a Mac Catalyst app — the catalog compiles (via the Catalyst-specific `--platform macosx --ui-framework-family uikit` actool invocation) into `RNTester.app/Contents/Resources/RNAssets.bundle` with all packager images and no loose files, and the runtime uses the same `imageNamed:inBundle:` mechanism CocoaPods resource bundles use on Catalyst. (rn-tester doesn't ship a Catalyst config, so this isn't in CI, but the build is clean.)

Reviewed By: cipolleschi

Differential Revision: D40095766

Pulled By: javache

fbshipit-source-id: 18dfcb47ae5185ef279b20dd0087de9a31e930b4

Author: janicduplessis

packages/react-native/React/Base/RCTUtils.h

@@ -139,6 +139,11 @@ RCT_EXTERN NSData *__nullable RCTDecompressGzipData(NSData *__nullable data, NSU
 // (or nil, if the URL does not specify a path within the main bundle)
 RCT_EXTERN NSString *__nullable RCTBundlePathForURL(NSURL *__nullable URL);
 
+// Returns the asset catalog image name for a packager asset URL, or nil if the
+// URL is not a main-bundle packager asset. The name matches the identifier the
+// CLI uses when generating the catalog (see assetPathUtils.getResourceIdentifier).
+RCT_EXTERN NSString *__nullable RCTAssetCatalogNameForURL(NSURL *__nullable URL);
+
 // Returns the Path of Library directory
 RCT_EXTERN NSString *__nullable RCTLibraryPath(void);
 

packages/react-native/React/Base/RCTUtils.mm

@@ -13,6 +13,7 @@
 #import <objc/runtime.h>
 #import <zlib.h>
 #import <atomic>
+#import <vector>
 
 #import <UIKit/UIKit.h>
 
@@ -886,7 +887,8 @@ BOOL RCTIsGzippedData(NSData *__nullable data)
 static BOOL RCTIsImageAssetsPath(NSString *path)
 {
   NSString *extension = [path pathExtension];
-  return [extension isEqualToString:@"png"] || [extension isEqualToString:@"jpg"];
+  return
+      [extension isEqualToString:@"png"] || [extension isEqualToString:@"jpg"] || [extension isEqualToString:@"jpeg"];
 }
 
 BOOL RCTIsBundleAssetURL(NSURL *__nullable imageURL)
@@ -939,6 +941,115 @@ BOOL RCTIsLocalAssetURL(NSURL *__nullable imageURL)
   return bundleCache[key];
 }
 
+static BOOL RCTUseAssetCatalog(void)
+{
+  static BOOL useAssetCatalog = NO;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    useAssetCatalog = [[[NSBundle mainBundle] objectForInfoDictionaryKey:@"RCTUseAssetCatalog"] boolValue];
+  });
+  return useAssetCatalog;
+}
+
+// The bundle react-native-xcode.sh compiles packager image assets into
+// (RNAssets.bundle, an actool-compiled asset catalog inside the app).
+static NSBundle *__nullable RCTAssetCatalogBundle(void)
+{
+  static NSBundle *bundle;
+  static dispatch_once_t onceToken;
+  dispatch_once(&onceToken, ^{
+    NSURL *bundleURL = [[NSBundle mainBundle] URLForResource:@"RNAssets" withExtension:@"bundle"];
+    if (bundleURL != nil) {
+      bundle = [NSBundle bundleWithURL:bundleURL];
+    }
+  });
+  return bundle;
+}
+
+NSString *__nullable RCTAssetCatalogNameForURL(NSURL *__nullable URL)
+{
+  // The "assets/" prefix the packager uses for all image assets. The CLI strips
+  // it from the identifiers it names the imagesets with.
+  constexpr NSUInteger assetsPrefixLength = sizeof("assets/") - 1;
+
+  NSString *path = RCTBundlePathForURL(URL);
+  // Packager assets always live under "assets/". Anything else (sub-bundles,
+  // CodePush/OTA assets outside the main bundle) is not in the catalog.
+  if (path == nil || ![path hasPrefix:@"assets/"]) {
+    return nil;
+  }
+
+  // Other packager assets (gif, webp, ...) are copied as plain files and must
+  // use the regular loader.
+  if (!RCTIsImageAssetsPath(path)) {
+    return nil;
+  }
+
+  // File system paths come back decomposed (NFD); restore the precomposed form
+  // the packager saw on disk so non-ASCII characters filter out the same way
+  // they do in the CLI's identifier.
+  path = path.precomposedStringWithCanonicalMapping;
+
+  const NSUInteger length = path.length;
+  unichar stackBuffer[256];
+  std::vector<unichar> heapBuffer;
+  unichar *chars = stackBuffer;
+  if (length > 256) {
+    heapBuffer.resize(length);
+    chars = heapBuffer.data();
+  }
+  [path getCharacters:chars range:NSMakeRange(0, length)];
+
+  // Strip the file extension (guaranteed present by RCTIsImageAssetsPath) and
+  // an optional "@<scale>x" suffix (integer or fractional, e.g. "@2x",
+  // "@1.5x"). The catalog stores a single imageset per image and resolves the
+  // scale by name at runtime, see
+  // https://developer.apple.com/documentation/xcode/managing-assets-with-asset-catalogs
+  NSUInteger end = length - 1;
+  while (end > assetsPrefixLength && chars[end] != '.') {
+    end--;
+  }
+  if (end > assetsPrefixLength && chars[end - 1] == 'x') {
+    // Walk back over "@<digits>(.<digits>)?" ending at the "x".
+    NSUInteger cursor = end - 1;
+    while (cursor > assetsPrefixLength && chars[cursor - 1] >= '0' && chars[cursor - 1] <= '9') {
+      cursor--;
+    }
+    if (cursor < end - 1) {
+      if (chars[cursor - 1] == '@') {
+        end = cursor - 1;
+      } else if (chars[cursor - 1] == '.') {
+        NSUInteger integerPart = cursor - 1;
+        while (integerPart > assetsPrefixLength && chars[integerPart - 1] >= '0' && chars[integerPart - 1] <= '9') {
+          integerPart--;
+        }
+        if (integerPart < cursor - 1 && chars[integerPart - 1] == '@') {
+          end = integerPart - 1;
+        }
+      }
+    }
+  }
+
+  // Build the identifier in place in a single pass: skip the "assets/" prefix,
+  // lowercase, encode the folder structure with "_" and drop anything that is
+  // not a valid identifier character, producing the same identifier as
+  // getResourceIdentifier in the CLI, which names the imagesets.
+  NSUInteger resultLength = 0;
+  for (NSUInteger i = assetsPrefixLength; i < end; i++) {
+    unichar c = chars[i];
+    if (c == '/') {
+      chars[resultLength++] = '_';
+    } else if ((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '_') {
+      chars[resultLength++] = c;
+    } else if (c >= 'A' && c <= 'Z') {
+      chars[resultLength++] = c + ('a' - 'A');
+    }
+  }
+
+  NSString *name = [NSString stringWithCharacters:chars length:resultLength];
+  return name;
+}
+
 UIImage *__nullable RCTImageFromLocalBundleAssetURL(NSURL *imageURL)
 {
   if (![imageURL.scheme isEqualToString:@"file"]) {
@@ -955,6 +1066,35 @@ BOOL RCTIsLocalAssetURL(NSURL *__nullable imageURL)
 
 UIImage *__nullable RCTImageFromLocalAssetURL(NSURL *imageURL)
 {
+  if (RCTUseAssetCatalog()) {
+    NSString *catalogName = RCTAssetCatalogNameForURL(imageURL);
+    if (catalogName != nil) {
+      // The app opted into the asset catalog and this is a packager asset, so it
+      // was compiled into RNAssets.bundle at build time. Trust the catalog and
+      // return directly, keeping the common path a single lookup with no
+      // filesystem fallback. Non-catalog assets (nil name) fall through below.
+      NSBundle *assetCatalogBundle = RCTAssetCatalogBundle();
+      if (assetCatalogBundle == nil) {
+        // Passing a nil bundle to imageNamed:inBundle: would silently search the
+        // main bundle instead, potentially resolving an unrelated app image.
+        RCTLogError(
+            @"RCTUseAssetCatalog is enabled but RNAssets.bundle was not found in the app. Image assets must be "
+             "bundled by react-native-xcode.sh, which compiles them into the app at build time. (loading %@)",
+            imageURL);
+        return nil;
+      }
+      UIImage *image = [UIImage imageNamed:catalogName inBundle:assetCatalogBundle compatibleWithTraitCollection:nil];
+      if (image == nil) {
+        RCTLogError(
+            @"Image \"%@\" (%@) was not found in the asset catalog. RCTUseAssetCatalog is enabled, "
+             "so image assets must be compiled into the app's RNAssets.bundle at build time.",
+            catalogName,
+            imageURL);
+      }
+      return image;
+    }
+  }
+
   NSString *imageName = RCTBundlePathForURL(imageURL);
 
   NSBundle *bundle = nil;

packages/react-native/package.json

@@ -114,6 +114,7 @@
     "scripts/react-native-xcode.sh",
     "scripts/setup-apple-spm.js",
     "scripts/spm",
+    "scripts/xcode/asset-catalog.sh",
     "scripts/xcode/ccache-clang.sh",
     "scripts/xcode/ccache-clang++.sh",
     "scripts/xcode/ccache.conf",

packages/react-native/scripts/react-native-xcode.sh

@@ -171,6 +171,13 @@ else
   EXTRA_ARGS+=("--config-cmd" "'$NODE_BINARY' $NODE_ARGS '$REACT_NATIVE_DIR/cli.js' config")
 fi
 
+# shellcheck source=/dev/null
+source "$REACT_NATIVE_DIR/scripts/xcode/asset-catalog.sh"
+ASSET_CATALOG_STAGING_DIR="$(asset_catalog_staging_dir)"
+if [[ -n "$ASSET_CATALOG_STAGING_DIR" ]]; then
+  EXTRA_ARGS+=("--asset-catalog-dest" "$ASSET_CATALOG_STAGING_DIR")
+fi
+
 # shellcheck disable=SC2086
 "$NODE_BINARY" $NODE_ARGS "$CLI_PATH" $BUNDLE_COMMAND \
   $CONFIG_ARG \
@@ -183,6 +190,8 @@ fi
   "${EXTRA_ARGS[@]}" \
   $EXTRA_PACKAGER_ARGS
 
+asset_catalog_compile "$ASSET_CATALOG_STAGING_DIR"
+
 if [[ $USE_HERMES == false ]]; then
   cp "$BUNDLE_FILE" "$DEST/"
   BUNDLE_FILE="$DEST/$BUNDLE_NAME.jsbundle"

packages/react-native/scripts/xcode/asset-catalog.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Bundles packager image assets into a compiled asset catalog (RNAssets.bundle)
+# inside the app, where the native image loader resolves them by name. Sourced
+# by react-native-xcode.sh.
+#
+# The feature is opt-in via the RCTUseAssetCatalog key in the app's Info.plist,
+# which is the same key the native image loader reads, so bundling and runtime
+# cannot disagree on where image assets live. The catalog is fully owned by
+# these functions (staged in derived files, compiled with actool into the app's
+# resources next to the js bundle), so the app's Xcode project needs no
+# changes. Apps that have not migrated are unaffected.
+#
+# After changing the RCTUseAssetCatalog key, do a clean build: incremental
+# builds do not remove image assets a previous build placed in the app with the
+# other setting (they are unused but add dead weight).
+
+# Prints the directory the bundler should emit image assets into (via
+# --asset-catalog-dest), or nothing if the app has not opted into the asset
+# catalog with the RCTUseAssetCatalog Info.plist key.
+asset_catalog_staging_dir() {
+  [[ "$BUNDLE_PLATFORM" == "ios" && -n "$PRODUCT_SETTINGS_PATH" ]] || return 0
+
+  local use_asset_catalog
+  use_asset_catalog="$(/usr/libexec/PlistBuddy -c 'Print :RCTUseAssetCatalog' "$PRODUCT_SETTINGS_PATH" 2>/dev/null || true)"
+  # Accept the value forms NSBundle's boolValue treats as true, so this check
+  # cannot disagree with the native runtime check.
+  case "$(echo "$use_asset_catalog" | tr '[:upper:]' '[:lower:]')" in
+    true | yes | 1) ;;
+    *) return 0 ;;
+  esac
+
+  local staging_dir="${DERIVED_FILE_DIR:-$(mktemp -d)}/rn-assets"
+  rm -rf "$staging_dir"
+  mkdir -p "$staging_dir/RNAssets.xcassets"
+  printf '%s\n' "$staging_dir"
+}
+
+# Compiles the staging catalog ($1, as returned by asset_catalog_staging_dir)
+# into RNAssets.bundle inside the app. The compiled Assets.car resolves the
+# right scale by name at runtime, see
+# https://developer.apple.com/documentation/xcode/managing-assets-with-asset-catalogs
+asset_catalog_compile() {
+  local staging_dir="$1"
+  local rn_assets_bundle="$DEST/RNAssets.bundle"
+  # Always remove first so a stale bundle from a previous build does not ship
+  # when the app opts out or has no image assets.
+  rm -rf "$rn_assets_bundle"
+  [[ -n "$staging_dir" ]] || return 0
+  if [[ -z "$(find "$staging_dir/RNAssets.xcassets" -maxdepth 1 -name '*.imageset' -print -quit)" ]]; then
+    return 0
+  fi
+
+  mkdir -p "$rn_assets_bundle"
+  local actool_args=("--platform" "${PLATFORM_NAME:-iphoneos}")
+  # These are always iOS-family image assets (this runs only for BUNDLE_PLATFORM
+  # "ios", which includes Mac Catalyst), so the deployment target must be an iOS
+  # version. On Catalyst the platform is macosx but MACOSX_DEPLOYMENT_TARGET is a
+  # macOS version (e.g. 10.15); passing that as the target makes actool silently
+  # emit loose files instead of a compiled Assets.car, so it must not be used.
+  actool_args+=("--minimum-deployment-target" "${IPHONEOS_DEPLOYMENT_TARGET:-15.1}")
+  case "${TARGETED_DEVICE_FAMILY:-1}" in *1*) actool_args+=("--target-device" "iphone") ;; esac
+  case "${TARGETED_DEVICE_FAMILY:-1}" in *2*) actool_args+=("--target-device" "ipad") ;; esac
+  if [[ "${IS_MACCATALYST:-NO}" == "YES" ]]; then
+    actool_args+=("--ui-framework-family" "uikit")
+  fi
+
+  # Surface actool diagnostics in the build log: without these flags actool
+  # suppresses them entirely, and it exits 0 even when it drops an imageset.
+  local actool_output
+  actool_output="$(xcrun actool "$staging_dir/RNAssets.xcassets" \
+    --compile "$rn_assets_bundle" \
+    --output-format human-readable-text \
+    --errors --warnings --notices \
+    "${actool_args[@]}" 2>&1)" || true
+  echo "$actool_output"
+  if [[ ! -f "$rn_assets_bundle/Assets.car" ]]; then
+    echo "error: failed to compile image assets into RNAssets.bundle. See actool output above." >&2
+    exit 2
+  fi
+
+  cat > "$rn_assets_bundle/Info.plist" <<'RN_ASSETS_PLIST'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleIdentifier</key>
+  <string>org.reactjs.RNAssets</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleName</key>
+  <string>RNAssets</string>
+  <key>CFBundlePackageType</key>
+  <string>BNDL</string>
+</dict>
+</plist>
+RN_ASSETS_PLIST
+}

packages/rn-tester/RNTester/Info.plist

@@ -48,6 +48,8 @@
 	<string>You need to add NSPhotoLibraryUsageDescription key in Info.plist to enable photo library usage, otherwise it is going to *fail silently*!</string>
 	<key>RCTNewArchEnabled</key>
 	<true/>
+	<key>RCTUseAssetCatalog</key>
+	<true/>
 	<key>UILaunchStoryboardName</key>
 	<string>LaunchScreen</string>
 	<key>UIRequiredDeviceCapabilities</key>