Document the iOS asset catalog option for image assets (#5177)

Author: janicduplessis

docs/images.md

@@ -65,6 +65,21 @@ const icon = this.props.active
 
 Note that image sources required this way include size (width, height) info for the Image. If you need to scale the image dynamically (i.e. via flex), you may need to manually set `{width: undefined, height: undefined}` on the style attribute.
 
+### Bundling images in an asset catalog (iOS)
+
+By default the bundler copies each required image, along with every `@2x` and `@3x` variant, into your iOS app as a loose file next to the JavaScript bundle. On iOS you can instead have them compiled into an [asset catalog](https://developer.apple.com/documentation/xcode/managing-assets-with-asset-catalogs), so the system ships only the scale a device needs.
+
+To opt in, set the `RCTUseAssetCatalog` key to `true` in your app's `Info.plist`:
+
+```xml
+<key>RCTUseAssetCatalog</key>
+<true/>
+```
+
+With this enabled, the iOS build script compiles your bundled images into an `RNAssets.bundle` asset catalog at build time. Your `require('./my-icon.png')` calls stay exactly the same, and no changes to your Xcode project are needed.
+
+After changing this setting, make sure to do a clean build.
+
 ## Static Non-Image Resources
 
 The `require` syntax described above can be used to statically include audio, video or document files in your project as well. Most common file types are supported including `.mp3`, `.wav`, `.mp4`, `.mov`, `.html`, `.pdf` and more. See [bundler defaults](https://github.com/facebook/metro/blob/main/packages/metro-config/src/defaults/defaults.js#L16-L51) for the full list.