Create @react-native/asset-utils package (#57368)

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/asset-utils/src/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 * 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/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', () => {

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

@@ -12,7 +12,9 @@ import getAssetDestPathAndroid from '../getAssetDestPathAndroid';
 
 const path = require('path');
 
-jest.dontMock('../getAssetDestPathAndroid').dontMock('../assetPathUtils');
+jest
+  .dontMock('../getAssetDestPathAndroid')
+  .dontMock('@react-native/asset-utils');
 
 describe('getAssetDestPathAndroid', () => {
   test('should use the right destination folder', () => {

packages/community-cli-plugin/src/commands/bundle/assetCatalogIOS.js

@@ -10,7 +10,7 @@
 
 import type {AssetData} from 'metro';
 
-import assetPathUtils from './assetPathUtils';
+import {getAndroidResourceIdentifier} from '@react-native/asset-utils';
 import fs from 'fs';
 import path from 'path';
 
@@ -33,7 +33,7 @@ export function getImageSet(
   asset: AssetData,
   scales: ReadonlyArray<number>,
 ): ImageSet {
-  const fileName = assetPathUtils.getResourceIdentifier(asset);
+  const fileName = getAndroidResourceIdentifier(asset);
   return {
     basePath: path.join(catalogDir, `${fileName}.imageset`),
     files: scales.map((scale, idx) => {