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

.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/asset-utils/README.md

@@ -0,0 +1,23 @@
+# @react-native/asset-utils
+
+[![npm]](https://www.npmjs.com/package/@react-native/asset-utils) [![npm downloads]](https://www.npmjs.com/package/@react-native/asset-utils)
+
+[npm]: https://img.shields.io/npm/v/@react-native/asset-utils.svg?color=blue
+[npm downloads]: https://img.shields.io/npm/dm/@react-native/asset-utils.svg
+
+Android resource-path helpers used when copying React Native assets into `drawable-*` / `raw` folders. Consumed by bundling and build tooling; most apps never import this directly.
+
+## API
+
+```js
+import {
+  getAndroidResourceFolderName,
+  getAndroidResourceIdentifier,
+} from '@react-native/asset-utils';
+```
+
+| Export | Signature | Notes |
+|---|---|---|
+| `getAndroidResourceFolderName` | `(asset: PackagerAsset, scale: number) => string` | e.g. `drawable-xhdpi`; non-drawable types resolve to `raw` |
+| `getAndroidResourceIdentifier` | `(asset: PackagerAsset) => string` | Sanitised resource name |
+| `drawableFileTypes` | `Set<string>` | Asset types that map to a `drawable-*` folder |

packages/asset-utils/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@react-native/asset-utils",
+  "version": "0.87.0-main",
+  "description": "Asset path utilities for React Native.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/react/react-native.git",
+    "directory": "packages/asset-utils"
+  },
+  "homepage": "https://github.com/react/react-native/tree/HEAD/packages/asset-utils#readme",
+  "keywords": [
+    "react-native"
+  ],
+  "bugs": "https://github.com/react/react-native/issues",
+  "engines": {
+    "node": "^22.13.0 || ^24.3.0 || >= 26.0.0"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "!**/__docs__/**",
+    "!**/__fixtures__/**",
+    "!**/__mocks__/**",
+    "!**/__tests__/**"
+  ]
+}

packages/asset-utils/src/AndroidPathUtils.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ *
+ * @format
+ */
+
+export type PackagerAsset = Readonly<{
+  httpServerLocation: string;
+  name: string;
+  type: string;
+}>;
+
+export function getAndroidResourceFolderName(
+  asset: PackagerAsset,
+  scale: number,
+): string;
+
+export function getAndroidResourceIdentifier(asset: PackagerAsset): string;
+
+export const drawableFileTypes: Set<string>;

packages/asset-utils/src/AndroidPathUtils.js

@@ -0,0 +1,93 @@
+/**
+ * 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.
+ *
+ * @flow strict
+ * @format
+ */
+
+'use strict';
+
+/*::
+// Conforms to the `PackagerAsset` type from `react-native`.
+export type PackagerAsset = Readonly<{
+  httpServerLocation: string,
+  name: string,
+  type: string,
+  ...
+}>;
+*/
+
+const androidScaleSuffix /*: {[string]: string} */ = {
+  '0.75': 'ldpi',
+  '1': 'mdpi',
+  '1.5': 'hdpi',
+  '2': 'xhdpi',
+  '3': 'xxhdpi',
+  '4': 'xxxhdpi',
+};
+
+const ANDROID_BASE_DENSITY = 160;
+
+// FIXME: Using number to represent discrete scale numbers is fragile in
+// essence because of floating point number imprecision.
+function getAndroidAssetSuffix(scale /*: number */) /*: string */ {
+  if (scale.toString() in androidScaleSuffix) {
+    return androidScaleSuffix[scale.toString()];
+  }
+
+  // NOTE: Android Gradle Plugin does not fully support the nnndpi format.
+  // See https://issuetracker.google.com/issues/72884435
+  if (Number.isFinite(scale) && scale > 0) {
+    return Math.round(scale * ANDROID_BASE_DENSITY) + 'dpi';
+  }
+
+  throw new Error('no such scale ' + scale.toString());
+}
+
+// See https://developer.android.com/guide/topics/resources/drawable-resource.html
+const drawableFileTypes /*: Set<string> */ = new Set([
+  'gif',
+  'heic',
+  'heif',
+  'jpeg',
+  'jpg',
+  'ktx',
+  'png',
+  'webp',
+  'xml',
+]);
+
+function getAndroidResourceFolderName(
+  asset /*: PackagerAsset */,
+  scale /*: number */,
+) /*: string */ {
+  if (!drawableFileTypes.has(asset.type)) {
+    return 'raw';
+  }
+
+  return 'drawable-' + getAndroidAssetSuffix(scale);
+}
+
+function getAndroidResourceIdentifier(
+  asset /*: PackagerAsset */,
+) /*: string */ {
+  return (getBasePath(asset) + '/' + asset.name)
+    .toLowerCase()
+    .replace(/\//g, '_') // Encode folder structure in file name
+    .replace(/([^a-z0-9_])/g, '') // Remove illegal chars
+    .replace(/^(?:assets|assetsunstable_path)_/, ''); // Remove "assets_" or "assetsunstable_path_" prefix
+}
+
+function getBasePath(asset /*: PackagerAsset */) /*: string */ {
+  const basePath = asset.httpServerLocation;
+  return basePath.startsWith('/') ? basePath.slice(1) : basePath;
+}
+
+module.exports = {
+  drawableFileTypes,
+  getAndroidResourceFolderName,
+  getAndroidResourceIdentifier,
+};

packages/asset-utils/src/__tests__/AndroidPathUtils-test.js

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+import {getAndroidResourceFolderName} from '../AndroidPathUtils';
+
+const DRAWABLE_ASSET = {
+  httpServerLocation: '/assets/',
+  name: 'foo',
+  type: 'png',
+};
+
+const NON_DRAWABLE_ASSET = {
+  httpServerLocation: '/assets/',
+  name: 'foo',
+  type: 'txt',
+};
+
+describe('getAndroidResourceFolderName', () => {
+  test('supports the six primary density buckets', () => {
+    expect(getAndroidResourceFolderName(DRAWABLE_ASSET, 0.75)).toBe(
+      'drawable-ldpi',
+    );
+    expect(getAndroidResourceFolderName(DRAWABLE_ASSET, 1)).toBe(
+      'drawable-mdpi',
+    );
+    expect(getAndroidResourceFolderName(DRAWABLE_ASSET, 1.5)).toBe(
+      'drawable-hdpi',
+    );
+    expect(getAndroidResourceFolderName(DRAWABLE_ASSET, 2)).toBe(
+      'drawable-xhdpi',
+    );
+    expect(getAndroidResourceFolderName(DRAWABLE_ASSET, 3)).toBe(
+      'drawable-xxhdpi',
+    );
+    expect(getAndroidResourceFolderName(DRAWABLE_ASSET, 4)).toBe(
+      'drawable-xxxhdpi',
+    );
+  });
+
+  test('supports nonstandard densities', () => {
+    expect(getAndroidResourceFolderName(DRAWABLE_ASSET, 1.25)).toBe(
+      'drawable-200dpi',
+    );
+    expect(getAndroidResourceFolderName(DRAWABLE_ASSET, 1.66)).toBe(
+      'drawable-266dpi',
+    );
+    expect(getAndroidResourceFolderName(DRAWABLE_ASSET, 1.33)).toBe(
+      'drawable-213dpi',
+    ); // ~tvdpi
+  });
+
+  test('throws if the density cannot be processed', () => {
+    expect(() => getAndroidResourceFolderName(DRAWABLE_ASSET, -1)).toThrow();
+    expect(() => getAndroidResourceFolderName(DRAWABLE_ASSET, 0)).toThrow();
+    expect(() =>
+      getAndroidResourceFolderName(DRAWABLE_ASSET, Infinity),
+    ).toThrow();
+  });
+
+  test('returns "raw" for non-drawables', () => {
+    expect(getAndroidResourceFolderName(NON_DRAWABLE_ASSET, 0.75)).toBe('raw');
+    expect(getAndroidResourceFolderName(NON_DRAWABLE_ASSET, 1)).toBe('raw');
+    expect(getAndroidResourceFolderName(NON_DRAWABLE_ASSET, 1.25)).toBe('raw');
+  });
+});

packages/react-native/Libraries/Image/AssetRegistry.js → packages/asset-utils/src/index.d.ts

@@ -4,11 +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
  * @format
  */
 
-export {
-  registerAsset,
-  getAssetByID,
-} from '@react-native/assets-registry/registry';
+export * from './AndroidPathUtils';

packages/asset-utils/src/index.js

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ *
+ * @flow strict
+ * @format
+ */
+
+'use strict';
+
+/*::
+export type {PackagerAsset} from './AndroidPathUtils';
+*/
+
+module.exports = require('./AndroidPathUtils');

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/community-cli-plugin/package.json

@@ -31,6 +31,7 @@
     "prepack": "node ../../scripts/build/prepack.js"
   },
   "dependencies": {
+    "@react-native/asset-utils": "0.87.0-main",
     "@react-native/dev-middleware": "0.87.0-main",
     "debug": "^4.4.0",
     "invariant": "^2.2.4",

packages/community-cli-plugin/src/commands/bundle/__tests__/filterPlatformAssetScales-test.js

@@ -10,7 +10,7 @@
 
 import filterPlatformAssetScales from '../filterPlatformAssetScales';
 
-jest.dontMock('../filterPlatformAssetScales').dontMock('../assetPathUtils');
+jest.dontMock('../filterPlatformAssetScales');
 
 describe('filterPlatformAssetScales', () => {
   test('removes everything but 2x and 3x for iOS', () => {