From 715eeaad69ad4b69dc5694fb5fba6dbde922ca06 Mon Sep 17 00:00:00 2001
From: Alex Hunt <huntie@meta.com>
Date: Mon, 6 Jul 2026 10:32:14 -0700
Subject: [PATCH] Deprecate @react-native/assets-registry (#57370)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Summary:
Pull Request resolved: https://github.com/react/react-native/pull/57370

**Context**

This stack intends to relocate the `AssetRegistry` API from `react-native/assets-registry` into `react-native` — addressing runtime safety and public deep imports issues (1.0 and JS Stable API blockers).

**This diff**

Deprecate the `react-native/assets-registry` package, replaced by changes in the last two diffs:

- `react-native/assets-registry/registry` → use `AssetRegistry` from `react-native` (or the `react-native/asset-registry` build entry point).
- `react-native/assets-registry/path-support` → use `react-native/asset-utils`.

**Deprecation plan**

The package will be deprecated for **two release cycles** (0.87 + 0.88) and deleted in 0.89.

Changelog:
[General][Deprecated] - Deprecate `react-native/assets-registry`. Use `AssetRegistry` from `react-native` and `react-native/asset-utils` instead.

Reviewed By: cortinico

Differential Revision: D110053924

fbshipit-source-id: 877a8f1b155232ccca037db6834fbcd9e0b0cc68
---
 packages/assets-registry/README.md         | 18 ++++++++++++++----
 packages/assets-registry/path-support.d.ts |  9 +++++++++
 packages/assets-registry/registry.d.ts     | 12 ++++++++++++
 3 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/packages/assets-registry/README.md b/packages/assets-registry/README.md
index 04f17cacffc..1dd81110155 100644
--- a/packages/assets-registry/README.md
+++ b/packages/assets-registry/README.md
@@ -2,23 +2,33 @@
 
 ![npm package](https://img.shields.io/npm/v/@react-native/assets-registry?color=brightgreen&label=npm%20package)
 
+> [!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)
 
-> [!Note]
-> Aliases to [`AssetRegistry`](https://reactnative.dev/docs/assetregistry) (since 0.87). Prefer importing directly from the `'react-native'` package in libraries.
+> [!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.
 
diff --git a/packages/assets-registry/path-support.d.ts b/packages/assets-registry/path-support.d.ts
index abdea750aac..cddc55f69ba 100644
--- a/packages/assets-registry/path-support.d.ts
+++ b/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;
diff --git a/packages/assets-registry/registry.d.ts b/packages/assets-registry/registry.d.ts
index 7509ef9ba13..fb8bfcc2a15 100644
--- a/packages/assets-registry/registry.d.ts
+++ b/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;