Move AssetRegistry implementation into main package, expose as public API (#57369)

Summary:
Pull Request resolved: #57369

**Problem**

The separate `react-native/assets-registry` package includes a longstanding ecosystem footgun.

`registry.js` holds asset state in a module-scoped variable, which makes the package a stateful singleton: exactly one instance must exist per JS runtime, or registration and lookup diverge.

We provide no guarantee that this singleton requirement holds:

- The install layout — how the package manager dedupes packages in `node_modules` — decides how many copies exist, and `react-native`'s exact-version pin means third-party ranges never dedupe against it.

Effects:

- **Consumers silently break**: `expo-asset` and `expo-image` can land on a second copy: assets register in one, resolve as `undefined` from the other. Expo neutralizes this with a shim in `expo/cli` that redirects every registry import to a single virtual module — bare React Native + Metro has no such protection.
- **This blocks 1.0**: The ecosystem can't move from exact-version lockstep to semver ranges until stateful packages like the asset registry are safe to duplicate. Today, relaxing the pin would turn a latent footgun into a common one.

**To solve this**, move towards (but not quite yet) deleting `react-native/assets-registry`, in favour of a replacement `AssetRegistry` API offered directly by `react-native`.

**Key changes**

NOTE: **Reviewer note**: Browsing file changes on GitHub may be more focused — https://github.com/react/react-native/pull/57369/changes

NOTE: Squash of #57233 (D108750302) and #57232 (D108750303)

`'react-native'`:
- Add new `AssetRegistry` API, along with the `PackagerAsset` and `AssetDestPathResolver` root type exports in `react-native`.
- Add a new `'react-native/asset-registry'` secondary entry point — intended for Metro's `transformer.assetRegistryPath` config contract.

`react-native/assets-registry`:
- Update to source from this relocated implementation — fixing the duplicate install layout bug (where apps/frameworks enforce a single copy of `react-native`).

**Impact**

- **✅ Fixed**: Imports from either `react-native` or `react-native/assets-registry` in RN 0.87+ will be durable to duplicate package installs — Expo can remove their virtual module shim.
- **✅ Fixed**: Deep import `'react-native/Libraries/Image/AssetRegistry'` dependency removed (migrated in `react-native/metro-config`).

Changelog:
- [General][Fixed] - **assets-registry**: `react-native/assets-registry` now shares state across duplicate installs, sourcing from a relocated implementation in the `react-native` package
- [General][Added] - Add `AssetRegistry` API (replaces `react-native/assets-registry/registry`)
- [General][Breaking] - `react-native/Libraries/Image/AssetRegistry` is removed. Please use the `AssetRegistry` API (apps/library code) and/or the `react-native/asset-registry` entrypoint (Metro/build configs).

Differential Revision: D109019622

Author: huntie

.eslintrc.js

@@ -50,7 +50,6 @@ module.exports = {
       files: [
         './packages/react-native/Libraries/**/*.{js,flow}',
         './packages/react-native/src/**/*.{js,flow}',
-        './packages/assets-registry/registry.js',
       ],
       parser: 'hermes-eslint',
       rules: {

packages/assets-registry/README.md

@@ -1,9 +1,6 @@
 # @react-native/assets-registry
 
-[![npm]](https://www.npmjs.com/package/@react-native/assets-registry) [![npm downloads]](https://www.npmjs.com/package/@react-native/assets-registry)
-
-[npm]: https://img.shields.io/npm/v/@react-native/assets-registry.svg?color=blue
-[npm downloads]: https://img.shields.io/npm/dm/@react-native/assets-registry.svg
+![npm package](https://img.shields.io/npm/v/@react-native/assets-registry?color=brightgreen&label=npm%20package)
 
 Runtime registry that maps asset IDs generated in a Metro bundle to asset metadata. It backs `<Image>`, `Image.resolveAssetSource()`, and any code that resolves `require('./img.png')` on native.
 
@@ -13,6 +10,9 @@ Most apps never import this directly — assets are handled through `<Image>`.
 
 ### `@react-native/assets-registry/registry`
 
+> [!Note]
+> Aliases to [`AssetRegistry`](https://reactnative.dev/docs/assetregistry) (since 0.87). Prefer importing directly from the `'react-native'` package in libraries.
+
 | Export | Signature | Notes |
 |---|---|---|
 | `registerAsset` | `(asset: PackagerAsset) => number` | Stores the asset; returns a numeric ID |

packages/assets-registry/package.json

@@ -26,5 +26,8 @@
     "!**/__fixtures__/**",
     "!**/__mocks__/**",
     "!**/__tests__/**"
-  ]
+  ],
+  "peerDependencies": {
+    "react-native": "*"
+  }
 }

packages/assets-registry/path-support.js

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @flow strict
+ * @flow strict-local
  * @format
  */
 

packages/assets-registry/registry.js

@@ -4,41 +4,20 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @flow strict
+ * @flow strict-local
  * @format
  */
 
 'use strict';
 
-/*::
-export type AssetDestPathResolver = 'android' | 'generic';
+import {AssetRegistry} from 'react-native';
 
-export type PackagerAsset = {
-  readonly __packager_asset: boolean,
-  readonly fileSystemLocation: string,
-  readonly httpServerLocation: string,
-  readonly width: ?number,
-  readonly height: ?number,
-  readonly scales: Array<number>,
-  readonly hash: string,
-  readonly name: string,
-  readonly type: string,
-  readonly resolver?: AssetDestPathResolver,
-  ...
-};
+/*::
+export type {AssetDestPathResolver, PackagerAsset} from 'react-native';
 */
 
-const assets /*: Array<PackagerAsset> */ = [];
-
-function registerAsset(asset /*: PackagerAsset */) /*: number */ {
-  // `push` returns new array length, so the first asset will
-  // get id 1 (not 0) to make the value truthy
-  return assets.push(asset);
-}
-
-function getAssetByID(assetId /*: number */) /*: PackagerAsset */ {
-  return assets[assetId - 1];
-}
-
 // eslint-disable-next-line @react-native/monorepo/no-commonjs-exports
-module.exports = {registerAsset, getAssetByID};
+module.exports = {
+  registerAsset: AssetRegistry.registerAsset,
+  getAssetByID: AssetRegistry.getAssetByID,
+};

packages/eslint-plugin-react-native/no-deep-imports.js

@@ -32,6 +32,7 @@ module.exports = {
         if (
           !isDeepReactNativeImport(node.source) ||
           isInitializeCoreImport(node.source) ||
+          isSecondaryEntryPoint(node.source) ||
           isFbInternalImport(node.source)
         ) {
           return;
@@ -88,6 +89,7 @@ module.exports = {
         if (
           !isDeepRequire(node) ||
           isInitializeCoreImport(node.arguments[0]) ||
+          isSecondaryEntryPoint(node.arguments[0]) ||
           isFbInternalImport(node.arguments[0])
         ) {
           return;
@@ -173,6 +175,14 @@ module.exports = {
       return source.value === 'react-native/Libraries/Core/InitializeCore';
     }
 
+    function isSecondaryEntryPoint(source) {
+      if (source.type !== 'Literal' || typeof source.value !== 'string') {
+        return false;
+      }
+
+      return source.value === 'react-native/asset-registry';
+    }
+
     function isFbInternalImport(source) {
       if (source.type !== 'Literal' || typeof source.value !== 'string') {
         return false;

packages/metro-config/src/index.flow.js

@@ -84,7 +84,7 @@ export function getDefaultConfig(projectRoot: string): ConfigT {
     },
     transformer: {
       allowOptionalDependencies: true,
-      assetRegistryPath: 'react-native/Libraries/Image/AssetRegistry',
+      assetRegistryPath: 'react-native/asset-registry',
       asyncRequireModulePath: require.resolve(
         'metro-runtime/src/modules/asyncRequire',
       ),

packages/react-native/Libraries/Image/AssetRegistry.js

@@ -10,31 +10,10 @@
 
 'use strict';
 
-export type ResolvedAssetSource = {
-  readonly __packager_asset: boolean,
-  readonly width: ?number,
-  readonly height: ?number,
-  readonly uri: string,
-  readonly scale: number,
-};
-
-// From @react-native/assets-registry
-type AssetDestPathResolver = 'android' | 'generic';
-
-// From @react-native/assets-registry
-type PackagerAsset = Readonly<{
-  __packager_asset: boolean,
-  fileSystemLocation: string,
-  httpServerLocation: string,
-  width: ?number,
-  height: ?number,
-  scales: Array<number>,
-  hash: string,
-  name: string,
-  type: string,
-  resolver?: AssetDestPathResolver,
-  ...
-}>;
+import type {
+  AssetDestPathResolver,
+  PackagerAsset,
+} from '../../src/private/assets/AssetRegistry';
 
 const PixelRatio = require('../Utilities/PixelRatio').default;
 const Platform = require('../Utilities/Platform').default;
@@ -45,6 +24,14 @@ const {
 } = require('@react-native/asset-utils');
 const invariant = require('invariant');
 
+export type ResolvedAssetSource = {
+  readonly __packager_asset: boolean,
+  readonly width: ?number,
+  readonly height: ?number,
+  readonly uri: string,
+  readonly scale: number,
+};
+
 /**
  * Returns a path like 'assets/AwesomeModule/icon@2x.png'
  */

packages/react-native/Libraries/Image/AssetSourceResolver.js

@@ -13,7 +13,7 @@
 // This is a stub for flow to make it understand require('./icon.png')
 // See metro/src/Bundler/index.js
 
-const AssetRegistry = require('@react-native/assets-registry/registry');
+const {AssetRegistry} = require('../../src/private/assets/AssetRegistry');
 
 const RelativeImageStub = AssetRegistry.registerAsset({
   __packager_asset: true,