Skip to content

Enable iOS asset catalog for image assets#247

Open
janicduplessis wants to merge 1 commit into
react-native-community:mainfrom
janicduplessis:@janic/ios-asset-catalog
Open

Enable iOS asset catalog for image assets#247
janicduplessis wants to merge 1 commit into
react-native-community:mainfrom
janicduplessis:@janic/ios-asset-catalog

Conversation

@janicduplessis

Copy link
Copy Markdown
Contributor

Summary:

Opt new apps into the iOS asset catalog for packager image assets, added in react/react-native#30129 (landed in main as 26769a00b23).

When the RCTUseAssetCatalog key is set in Info.plist, react-native-xcode.sh compiles bundled images into an RNAssets.bundle asset catalog (via actool) and the native image loader resolves them by name, instead of copying each image and every @2x/@3x variant as a loose file next to the JS bundle. The catalog lets the OS pick and load only the scale a device needs, which reduces app size and makes image lookups a single named catalog resolution.

The same key gates both the build script and the runtime loader, so bundling and lookup can't disagree about where assets live. Apps that don't set it are unaffected. The template tracks react-native: nightly, which includes the feature, so no version bump is needed here.

Changelog:

[IOS] [ADDED] - Enable the iOS asset catalog (RCTUseAssetCatalog) for image assets in new apps

Test Plan:

  • Init an app from this template and build for iOS.
  • Confirm RNAssets.bundle is produced in the app and its Assets.car contains the app's image assets.
  • Verify <Image source={require('./img.png')} /> renders at the correct scale on devices of different scales.
  • Note: after toggling this key, do a clean build — incremental builds don't remove image assets a previous build placed with the other setting.

@cortinico

Copy link
Copy Markdown
Member

Apps that don't set it are unaffected

Thanks for mentioning. cc @cipolleschi as this is a iOS change.
We're aiming at doing 0.88 with no breaking changes so all the template changes we're shipping should be optional (or wait till we cut the next branch)

@cortinico
cortinico requested a review from cipolleschi July 24, 2026 15:42
@cipolleschi

Copy link
Copy Markdown
Contributor

this is an additive change it is not mandatory to adopt

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants