Deprecate @react-native/assets-registry

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,24 +1,34 @@
 # @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 package](https://img.shields.io/npm/v/@react-native/assets-registry?color=brightgreen&label=npm%20package)
 
-[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
+> [!Warning]
+> **This package is deprecated (since 0.87)** and will be removed in a future release. Use [`AssetRegistry`](https://reactnative.dev/docs/assetregistry) from `react-native` (or the `react-native/asset-registry` build entry point) instead of `@react-native/assets-registry/registry`, and [`@react-native/asset-utils`](https://www.npmjs.com/package/@react-native/asset-utils) instead of `@react-native/assets-registry/path-support`.
 
 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.
 
 Most apps never import this directly — assets are handled through `<Image>`.
 
 ## API
 
-### `@react-native/assets-registry/registry`
+### `@react-native/assets-registry/registry` (DEPRECATED)
+
+> [!Warning]
+> **Deprecated**: Aliases to [`AssetRegistry`](https://reactnative.dev/docs/assetregistry) (since 0.87).
+>
+> Please use:
+> - `import { AssetRegistry } from 'react-native';` (apps/library code)
+> - `'react-native/asset-registry'` (entrypoint for Metro/build configs)
 
 | Export | Signature | Notes |
 |---|---|---|
 | `registerAsset` | `(asset: PackagerAsset) => number` | Stores the asset; returns a numeric ID |
 | `getAssetByID` | `(assetId: number) => PackagerAsset` | Looks an asset back up by ID |
 
-### `@react-native/assets-registry/path-support`
+### `@react-native/assets-registry/path-support` (DEPRECATED)
+
+> [!Warning]
+> **Deprecated**: Use [`@react-native/asset-utils`](https://www.npmjs.com/package/@react-native/asset-utils) (since 0.87).
 
 Android resource-path helpers, used when copying assets into `drawable-*` folders.
 

packages/assets-registry/package.json

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

packages/assets-registry/path-support.d.ts

@@ -9,11 +9,20 @@
 
 import type {PackagerAsset} from './registry';
 
+/**
+ * @deprecated Use `getAndroidResourceFolderName` from `@react-native/asset-utils` instead.
+ */
 export function getAndroidResourceFolderName(
   asset: PackagerAsset,
   scale: number,
 ): string;
 
+/**
+ * @deprecated Use `getAndroidResourceIdentifier` from `@react-native/asset-utils` instead.
+ */
 export function getAndroidResourceIdentifier(asset: PackagerAsset): string;
 
+/**
+ * @deprecated Use `@react-native/asset-utils` instead.
+ */
 export function getBasePath(asset: PackagerAsset): string;

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.d.ts

@@ -7,8 +7,14 @@
  * @format
  */
 
+/**
+ * @deprecated Use `import type {AssetDestPathResolver} from 'react-native'` instead.
+ */
 export type AssetDestPathResolver = 'android' | 'generic';
 
+/**
+ * @deprecated Use `import type {PackagerAsset} from 'react-native'` instead.
+ */
 export type PackagerAsset = {
   readonly __packager_asset: boolean;
   readonly fileSystemLocation: string;
@@ -22,6 +28,12 @@ export type PackagerAsset = {
   readonly resolver?: AssetDestPathResolver | undefined;
 };
 
+/**
+ * @deprecated Use `import {AssetRegistry} from 'react-native'` instead.
+ */
 export function registerAsset(asset: PackagerAsset): number;
 
+/**
+ * @deprecated Use `import {AssetRegistry} from 'react-native'` instead.
+ */
 export function getAssetByID(assetId: number): PackagerAsset;