Use asset catalog for iOS images

Load packager image assets from an iOS asset catalog (RNAssets.xcassets)
instead of loose files in the app bundle. The CLI bundler emits imagesets
into the catalog at build time (via --asset-catalog-dest, already in
@react-native/community-cli-plugin); Xcode compiles them into Assets.car and
the native image loader resolves them by name with [UIImage imageNamed:].

The catalog path is gated on the RCTUseAssetCatalog Info.plist key, a
build-time constant read once. Apps that have not migrated are unaffected and
the catalog path is a single lookup with no filesystem fallback; a mis-bundled
asset logs an RCTLogError instead of failing silently. The native side only
resolves catalog names for what the CLI actually emits into the catalog
(png/jpg/jpeg under main-bundle assets/, mirroring isCatalogAsset), so
gif/webp packager assets, sub-bundles and OTA assets outside the main bundle
fall through to the existing loader. jpeg is also added to
RCTIsImageAssetsPath so jpeg assets are routed to the bundle-asset loaders.

react-native-xcode.sh passes --asset-catalog-dest when an RNAssets.xcassets
exists next to the app's Info.plist. In rn-tester the "Build JS Bundle" phase
is ordered before Resources and declares the catalog as an output so the new
Xcode build system compiles it after it is populated (asset symbol generation
is disabled on the target to avoid a dependency cycle with that step).

Cold image loads in RNTester are ~15x faster (median 47us vs 719us) and Apple
app thinning can strip unused scales.

Author: janicduplessis

.gitignore

@@ -22,6 +22,9 @@ DerivedData
 project.xcworkspace
 **/.xcode.env.local
 
+# Generated iOS asset catalog imagesets (produced at build time from JS assets)
+**/RNAssets.xcassets/*.imageset
+
 # Gradle
 /build/
 /packages/rn-tester/build

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

@@ -886,7 +886,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 +940,75 @@ 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;
+}
+
+NSString *__nullable RCTAssetCatalogNameForURL(NSURL *__nullable URL)
+{
+  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;
+  }
+
+  // Only image types the CLI emits into the catalog (see isCatalogAsset in
+  // @react-native/community-cli-plugin). Other packager assets (gif, webp, ...)
+  // are copied as plain files and must use the regular loader.
+  if (!RCTIsImageAssetsPath(path)) {
+    return nil;
+  }
+
+  // Strip the optional "@Nx" scale suffix and the file extension in a single
+  // pass. Asset catalog images resolve the correct scale by name at runtime.
+  // See https://developer.apple.com/documentation/xcode/asset-catalogs
+  static NSRegularExpression *scaleAndExtensionRegex;
+  static dispatch_once_t scaleOnceToken;
+  dispatch_once(&scaleOnceToken, ^{
+    // Scales are not necessarily integers (e.g. "@1.5x").
+    scaleAndExtensionRegex = [NSRegularExpression regularExpressionWithPattern:@"(@\\d+(\\.\\d+)?x)?\\.\\w+$"
+                                                                       options:0
+                                                                         error:nil];
+  });
+  path = [scaleAndExtensionRegex stringByReplacingMatchesInString:path
+                                                          options:0
+                                                            range:NSMakeRange(0, path.length)
+                                                     withTemplate:@""];
+
+  // Lowercase and encode the folder structure into the name.
+  path = [path.lowercaseString stringByReplacingOccurrencesOfString:@"/" withString:@"_"];
+
+  // Remove characters that are not allowed in an asset catalog identifier.
+  static NSCharacterSet *illegalCharacters;
+  static dispatch_once_t illegalOnceToken;
+  dispatch_once(&illegalOnceToken, ^{
+    illegalCharacters =
+        [[NSCharacterSet characterSetWithCharactersInString:@"abcdefghijklmnopqrstuvwxyz0123456789_"] invertedSet];
+  });
+  path = [[path componentsSeparatedByCharactersInSet:illegalCharacters] componentsJoinedByString:@""];
+
+  // Remove the "assets_" (or "assetsunstable_path_") prefix.
+  static NSRegularExpression *prefixRegex;
+  static dispatch_once_t prefixOnceToken;
+  dispatch_once(&prefixOnceToken, ^{
+    prefixRegex = [NSRegularExpression regularExpressionWithPattern:@"^(assetsunstable_path|assets)_" options:0
+                                                             error:nil];
+  });
+  path = [prefixRegex stringByReplacingMatchesInString:path
+                                               options:0
+                                                 range:NSMakeRange(0, path.length)
+                                          withTemplate:@""];
+
+  return path;
+}
+
 UIImage *__nullable RCTImageFromLocalBundleAssetURL(NSURL *imageURL)
 {
   if (![imageURL.scheme isEqualToString:@"file"]) {
@@ -955,6 +1025,25 @@ 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.xcassets 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.
+      UIImage *image = [UIImage imageNamed:catalogName];
+      if (image == nil) {
+        RCTLogError(
+            @"Image \"%@\" (%@) was not found in the asset catalog. RCTUseAssetCatalog is enabled, "
+             "so image assets must be bundled into the app's RNAssets.xcassets at build time.",
+            catalogName,
+            imageURL);
+      }
+      return image;
+    }
+  }
+
   NSString *imageName = RCTBundlePathForURL(imageURL);
 
   NSBundle *bundle = nil;

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

@@ -151,6 +151,19 @@ else
   EXTRA_ARGS+=("--config-cmd" "'$NODE_BINARY' $NODE_ARGS '$REACT_NATIVE_DIR/cli.js' config")
 fi
 
+# iOS asset catalog: if the app has an RNAssets.xcassets next to its Info.plist,
+# emit image assets into it so Xcode compiles them into Assets.car and Apple app
+# thinning can strip unused scales. Presence of the catalog is the opt-in signal,
+# so apps that have not migrated are unaffected. This also covers Mac Catalyst
+# (BUNDLE_PLATFORM is forced to "ios" above). Pair with RCTUseAssetCatalog=YES in
+# the app's Info.plist so the native side loads from the catalog.
+if [[ "$BUNDLE_PLATFORM" == "ios" && -n "$PRODUCT_SETTINGS_PATH" ]]; then
+  ASSET_CATALOG_DIR="$(dirname "$PRODUCT_SETTINGS_PATH")"
+  if [[ -d "$ASSET_CATALOG_DIR/RNAssets.xcassets" ]]; then
+    EXTRA_ARGS+=("--asset-catalog-dest" "$ASSET_CATALOG_DIR")
+  fi
+fi
+
 # shellcheck disable=SC2086
 "$NODE_BINARY" $NODE_ARGS "$CLI_PATH" $BUNDLE_COMMAND \
   $CONFIG_ARG \

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>

packages/rn-tester/RNTester/RNAssets.xcassets/Contents.json

@@ -0,0 +1,6 @@
+{
+  "info" : {
+    "author" : "xcode",
+    "version" : 1
+  }
+}

packages/rn-tester/RNTesterPods.xcodeproj/project.pbxproj

@@ -7,6 +7,7 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
+		0CF641B628ECB21C00DCDD11 /* RNAssets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 0CF641B528ECB21C00DCDD11 /* RNAssets.xcassets */; };
 		0EA618032BE537D3001875EF /* RNTesterBundle.bundle in Resources */ = {isa = PBXBuildFile; fileRef = 0EA618022BE537D3001875EF /* RNTesterBundle.bundle */; };
 		13B07FC11A68108700A75B9A /* main.m in Sources */ = {isa = PBXBuildFile; fileRef = 13B07FB71A68108700A75B9A /* main.m */; };
 		2DDEF0101F84BF7B00DBDF73 /* Images.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 2DDEF00F1F84BF7B00DBDF73 /* Images.xcassets */; };
@@ -74,6 +75,7 @@
 /* End PBXContainerItemProxy section */
 
 /* Begin PBXFileReference section */
+		0CF641B528ECB21C00DCDD11 /* RNAssets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; name = RNAssets.xcassets; path = RNTester/RNAssets.xcassets; sourceTree = "<group>"; };
 		0EA618022BE537D3001875EF /* RNTesterBundle.bundle */ = {isa = PBXFileReference; lastKnownFileType = "wrapper.plug-in"; name = RNTesterBundle.bundle; path = RNTester/RNTesterBundle.bundle; sourceTree = "<group>"; };
 		13B07F961A680F5B00A75B9A /* RNTester.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = RNTester.app; sourceTree = BUILT_PRODUCTS_DIR; };
 		13B07FAF1A68108700A75B9A /* AppDelegate.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = AppDelegate.h; path = RNTester/AppDelegate.h; sourceTree = "<group>"; };
@@ -211,6 +213,7 @@
 				13B07FB71A68108700A75B9A /* main.m */,
 				832F45BA2A8A6E1F0097B4E6 /* SwiftTest.swift */,
 				2DDEF00F1F84BF7B00DBDF73 /* Images.xcassets */,
+				0CF641B528ECB21C00DCDD11 /* RNAssets.xcassets */,
 				8145AE05241172D900A3F8DA /* LaunchScreen.storyboard */,
 				680759612239798500290469 /* Fabric */,
 				272E6B3A1BEA846C001FCF37 /* NativeExampleViews */,
@@ -366,8 +369,8 @@
 				F28F13DD10D40D98C0BB7BE8 /* [CP] Check Pods Manifest.lock */,
 				13B07F871A680F5B00A75B9A /* Sources */,
 				13B07F8C1A680F5B00A75B9A /* Frameworks */,
-				13B07F8E1A680F5B00A75B9A /* Resources */,
 				68CD48B71D2BCB2C007E06A9 /* Build JS Bundle */,
+				13B07F8E1A680F5B00A75B9A /* Resources */,
 				79E8BE2B119D4C5CCD2F04B3 /* [RN] Copy Hermes Framework */,
 				17FE348EDF12252D972FFC2F /* [CP] Embed Pods Frameworks */,
 				DFEE284B22AD5E88BBF1026A /* [CP] Copy Pods Resources */,
@@ -470,6 +473,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				2DDEF0101F84BF7B00DBDF73 /* Images.xcassets in Resources */,
+				0CF641B628ECB21C00DCDD11 /* RNAssets.xcassets in Resources */,
 				8145AE06241172D900A3F8DA /* LaunchScreen.storyboard in Resources */,
 				0EA618032BE537D3001875EF /* RNTesterBundle.bundle in Resources */,
 				F0D621C32BBB9E38005960AC /* PrivacyInfo.xcprivacy in Resources */,
@@ -582,6 +586,7 @@
 		};
 		68CD48B71D2BCB2C007E06A9 /* Build JS Bundle */ = {
 			isa = PBXShellScriptBuildPhase;
+			alwaysOutOfDate = 1;
 			buildActionMask = 2147483647;
 			files = (
 			);
@@ -591,6 +596,7 @@
 			);
 			name = "Build JS Bundle";
 			outputPaths = (
+				"$(SRCROOT)/RNTester/RNAssets.xcassets",
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 			shellPath = /bin/sh;
@@ -801,6 +807,7 @@
 			baseConfigurationReference = CA59C9994B1822826D8983F0 /* Pods-RNTester.debug.xcconfig */;
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+				ASSETCATALOG_COMPILER_GENERATE_ASSET_SYMBOLS = NO;
 				CLANG_ENABLE_MODULES = YES;
 				DEVELOPMENT_TEAM = "";
 				HEADER_SEARCH_PATHS = (
@@ -839,6 +846,7 @@
 			baseConfigurationReference = 51BC9297B6C3163C14532020 /* Pods-RNTester.release.xcconfig */;
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+				ASSETCATALOG_COMPILER_GENERATE_ASSET_SYMBOLS = NO;
 				CLANG_ENABLE_MODULES = YES;
 				DEVELOPMENT_TEAM = "";
 				EXCLUDED_ARCHS = "";

packages/rn-tester/RNTesterUnitTests/RCTURLUtilsTests.m

@@ -100,4 +100,61 @@ - (void)testIsLocalAssetsURLParam
   XCTAssertFalse(RCTIsLocalAssetURL(otherAssetsURL));
 }
 
+- (void)testAssetCatalogNameForURL
+{
+  NSString *resourcePath = [[NSBundle mainBundle] resourcePath];
+
+  // Nested folder + "@2x" scale suffix: folders are encoded into the name, the
+  // scale suffix and extension are stripped, and the "assets_" prefix removed.
+  NSURL *scaledURL =
+      [NSURL fileURLWithPath:[resourcePath stringByAppendingPathComponent:@"assets/AwesomeModule/icon@2x.png"]];
+  XCTAssertEqualObjects(RCTAssetCatalogNameForURL(scaledURL), @"awesomemodule_icon");
+
+  // Same asset without a scale suffix resolves to the same name.
+  NSURL *unscaledURL =
+      [NSURL fileURLWithPath:[resourcePath stringByAppendingPathComponent:@"assets/AwesomeModule/icon.png"]];
+  XCTAssertEqualObjects(RCTAssetCatalogNameForURL(unscaledURL), @"awesomemodule_icon");
+
+  // Illegal characters (e.g. "-") are stripped, matching the CLI identifier.
+  NSURL *illegalCharsURL =
+      [NSURL fileURLWithPath:[resourcePath stringByAppendingPathComponent:@"assets/my-module/my-icon@3x.png"]];
+  XCTAssertEqualObjects(RCTAssetCatalogNameForURL(illegalCharsURL), @"mymodule_myicon");
+
+  // Non-integer scale suffixes are also stripped.
+  NSURL *fractionalScaleURL =
+      [NSURL fileURLWithPath:[resourcePath stringByAppendingPathComponent:@"assets/AwesomeModule/icon@1.5x.png"]];
+  XCTAssertEqualObjects(RCTAssetCatalogNameForURL(fractionalScaleURL), @"awesomemodule_icon");
+
+  // ".jpeg" is a catalog image type (matching the CLI's isCatalogAsset).
+  NSURL *jpegURL =
+      [NSURL fileURLWithPath:[resourcePath stringByAppendingPathComponent:@"assets/AwesomeModule/photo@2x.jpeg"]];
+  XCTAssertEqualObjects(RCTAssetCatalogNameForURL(jpegURL), @"awesomemodule_photo");
+
+  // Non-catalog image types (the CLI only emits png/jpg/jpeg into the catalog)
+  // are not catalog assets and use the regular loader.
+  NSURL *gifURL =
+      [NSURL fileURLWithPath:[resourcePath stringByAppendingPathComponent:@"assets/AwesomeModule/anim.gif"]];
+  XCTAssertNil(RCTAssetCatalogNameForURL(gifURL));
+
+  // Assets outside the project root are encoded with "_" by the packager
+  // (e.g. "assets/../../shared" -> "assets/__shared") and resolve to the same
+  // identifier the CLI generates.
+  NSURL *outOfRootURL =
+      [NSURL fileURLWithPath:[resourcePath stringByAppendingPathComponent:@"assets/__shared/icon@2x.png"]];
+  XCTAssertEqualObjects(RCTAssetCatalogNameForURL(outOfRootURL), @"__shared_icon");
+
+  // Query strings are ignored, same as the legacy loader.
+  NSURL *queryURL = [NSURL
+      URLWithString:[NSString stringWithFormat:@"file://%@/assets/AwesomeModule/icon@2x.png?platform=ios&hash=abc",
+                                               resourcePath]];
+  XCTAssertEqualObjects(RCTAssetCatalogNameForURL(queryURL), @"awesomemodule_icon");
+
+  // A non-packager path (not under "assets/") is not a catalog asset.
+  NSURL *notPackagerURL = [NSURL fileURLWithPath:[resourcePath stringByAppendingPathComponent:@"icon.png"]];
+  XCTAssertNil(RCTAssetCatalogNameForURL(notPackagerURL));
+
+  // A nil URL is handled gracefully.
+  XCTAssertNil(RCTAssetCatalogNameForURL(nil));
+}
+
 @end