Add unstable-internals entry point (#57489)

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

See [**RFC0894: Removing deep imports from react-native**](https://github.com/react-native-community/discussions-and-proposals/pull/894)

Adds a `'react-native/unstable-internals-do-not-use'` entry point that acts as an explicit, opt-in escape hatch for frameworks and libraries that depend on specific React Native internals.

Follows (and supersedes) https://github.com/react-native-community/discussions-and-proposals/pull/985.

Resolves T270727304.

**Motivation**

- Maintains a known list of which React Native internals are still in use.
- Decouples removal of the Strict API opt-out from the longer-term decisions about these APIs.
- Lets us relocate supporting source files freely, since consumers reference this subpath instead of deep internal paths.

**Notes**

- Reuses the runtime **object-with-getter pattern** (same as `index.js`), to avoid any native module side effects caused by loading adjacent file exports.
    - e.g. in Expo, [`hmrUtils.js`](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/async-require/hmrUtils.native.ts?fbclid=IwY2xjawS7GjNwZG9mA2V4dG4DYWVtAjExAGJyaWQRMTZ1ckEwU05oWUw2bDBVN21zcnRjBmFwcF9pZAEwAAEen3UuX4Ig-RD3n1ULZIHIHq21Mfk_ci9b2SxquY7UkngDs6qhnRt5YQlb8Os_aem_ylJy40egSOl1qhZ9bA9HTA) is designed to be run early in RN startup — preserve the lazy require characteristic and do not break this.
- TypeScript defs on this API are minimal, with complex internal input/handle types reduced to `unknown`. As with D110602194, these are intended to be feature-locked.

**Exposed internals and known consumers**

NOTE: The exports the community needs have reduced slightly since the spreadsheet in RFC0895 and would almost all align with `devsupport`. However, we're explicitly leaving a decision to formalise until later, and we may need to add in extra APIs quickly based on RC feedback.

| Export | Source module | Known consumers |
|---|---|---|
| `AppContainer` | `Libraries/ReactNative/AppContainer` | react-native-screens ([DebugContainer.tsx](https://github.com/software-mansion/react-native-screens/blob/6f38d76129d40cc8145d06b98f885b508fa7bf2d/src/components/DebugContainer.tsx#L5)) |
| `AssetSourceResolver` | `Libraries/Image/AssetSourceResolver` | Re.pack ([IncludeModules.ts](https://github.com/callstack/repack/blob/2498b3a426203daa4b81c7e6f7a88e86d88e77b9/packages/repack/src/modules/IncludeModules.ts#L9)) |
| `customDirectEventTypes` | `Libraries/Renderer/shims/ReactNativeViewConfigRegistry` | react-native-gesture-handler ([customDirectEventTypes.ts](https://github.com/software-mansion/react-native-gesture-handler/blob/ee147abf364bef48a02d3cf437572b4dddd30bec/packages/react-native-gesture-handler/src/handlers/customDirectEventTypes.ts#L2)) |
| `DevLoadingView` | `Libraries/Utilities/DevLoadingView` | Expo ([hmrUtils.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/async-require/hmrUtils.native.ts)), Re.pack ([WebpackHMRClient.ts](https://github.com/callstack/repack/blob/2498b3a426203daa4b81c7e6f7a88e86d88e77b9/packages/repack/src/modules/WebpackHMRClient.ts)) |
| `getDevServer` | `Libraries/Core/Devtools/getDevServer` | Expo ([getDevServer.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/async-require/getDevServer.native.ts), [hmrUtils.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/async-require/hmrUtils.native.ts), [base.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/dom/base.ts), [getDevServer.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/metro-runtime/src/getDevServer.native.ts), [devServerEndpoints.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/log-box/src/utils/devServerEndpoints.ts), [getConnectionInfo.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/devtools/src/getConnectionInfo.native.ts), [index.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo-router/src/getDevServer/index.native.ts)) |
| `HMRClient` | `Libraries/Utilities/HMRClient` | Expo ([metroServerLogs.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/metro-runtime/src/metroServerLogs.native.ts)) |
| `NativeExceptionsManager` | `Libraries/Core/NativeExceptionsManager` | Expo ([hmrUtils.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/async-require/hmrUtils.native.ts)), Re.pack ([WebpackHMRClient.ts](https://github.com/callstack/repack/blob/2498b3a426203daa4b81c7e6f7a88e86d88e77b9/packages/repack/src/modules/WebpackHMRClient.ts)) |
| `NativeRedBox` | `Libraries/NativeModules/specs/NativeRedBox` | Expo ([hmrUtils.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/async-require/hmrUtils.native.ts)), Re.pack ([WebpackHMRClient.ts](https://github.com/callstack/repack/blob/2498b3a426203daa4b81c7e6f7a88e86d88e77b9/packages/repack/src/modules/WebpackHMRClient.ts)) |
| `NativeSourceCode` | `Libraries/NativeModules/specs/NativeSourceCode` | Expo ([getBundleUrl.native.ts](https://github.com/expo/expo/blob/2d07e3a17f4be2284bbf579d8825fe32f762ce1a/packages/expo/src/utils/getBundleUrl.native.ts)) |
| `PressabilityDebugView` | `Libraries/Pressability/PressabilityDebug` | react-native-gesture-handler ([PressabilityDebugView.tsx](https://github.com/software-mansion/react-native-gesture-handler/blob/ee147abf364bef48a02d3cf437572b4dddd30bec/packages/react-native-gesture-handler/src/handlers/PressabilityDebugView.tsx#L2)) |

**Alternative names**

- `unstable-frameworks`
- `unstable-devsupport`
- `frameworks-private-interface` (mirroring `ReactPrivateInterface.js`) — this is likely a future stable shape candidate.

Changelog: [Internal]

Reviewed By: rubennorte

Differential Revision: D110911864

fbshipit-source-id: 4cb4758e6621a626916cc6543f9a1f8462f1d5b0
This commit is contained in:
Alex Hunt authored and meta-codesync[bot] committed 2026-07-10 06:00:50 -07:00
1 parent b7edeb7126
commit 4b7fa49c27
3 files changed
+295

No files matched your search

+5
View File
@@ -53,6 +53,11 @@
"default": "./src/react-private-interface.js"
},
"./setup-env": "./src/setup-env.js",
"./unstable-internals-do-not-use": {
"react-native-unstable-internals": "./src/unstable-internals-do-not-use.d.ts",
"types": null,
"default": "./src/unstable-internals-do-not-use.js"
},
"./src/fb_internal/*": "./src/fb_internal/*",
"./package.json": "./package.json"
},
@@ -0,0 +1,214 @@
/**
* 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
*/
// ----------------------------------------------------------------------------
// Types entry point for react-native/unstable-internals-do-not-use.
//
// IMPORTANT: Keep this file in sync with unstable-internals-do-not-use.js.
// ----------------------------------------------------------------------------
import type * as React from 'react';
// #region AppContainer
interface AppContainerProps {
children?: React.ReactNode | undefined;
rootTag: number;
initialProps?: object | undefined;
WrapperComponent?: React.ComponentType<any> | null | undefined;
rootViewStyle?: unknown | undefined;
internal_excludeLogBox?: boolean | undefined;
internal_excludeInspector?: boolean | undefined;
}
/** Root component that wraps and mounts a React Native app tree. */
export const AppContainer: React.ComponentType<AppContainerProps>;
// #endregion
// #region AssetSourceResolver
interface ResolvedAssetSource {
readonly __packager_asset: boolean;
readonly width: number | null | undefined;
readonly height: number | null | undefined;
readonly uri: string;
readonly scale: number;
}
/** Resolves a packager asset descriptor to a loadable source for the current platform. */
export class AssetSourceResolver {
serverUrl: string | null | undefined;
jsbundleUrl: string | null | undefined;
asset: unknown;
constructor(
serverUrl: string | null | undefined,
jsbundleUrl: string | null | undefined,
asset: unknown,
);
isLoadedFromServer(): boolean;
isLoadedFromFileSystem(): boolean;
defaultAsset(): ResolvedAssetSource;
getAssetUsingResolver(resolver: 'android' | 'generic'): ResolvedAssetSource;
assetServerURL(): ResolvedAssetSource;
scaledAssetPath(): ResolvedAssetSource;
scaledAssetURLNearBundle(): ResolvedAssetSource;
resourceIdentifierWithoutScale(): ResolvedAssetSource;
drawableFolderInBundle(): ResolvedAssetSource;
fromSource(source: string): ResolvedAssetSource;
static pickScale(scales: number[], deviceScale?: number): number;
}
// #endregion
// #region customDirectEventTypes
/** Registry mapping custom direct (non-bubbling) event names to their registration names. */
export const customDirectEventTypes: {
[eventName: string]: Readonly<{
registrationName: string;
}>;
};
// #endregion
// #region DevLoadingView
/** Dev-only overlay banner showing bundle load, refresh, and error status. */
export const DevLoadingView: {
showMessage(
message: string,
type: 'load' | 'refresh' | 'error',
options?: {dismissButton?: boolean | undefined},
): void;
hide(): void;
};
// #endregion
// #region getDevServer
interface DevServerInfo {
url: string;
fullBundleUrl: string | null;
bundleLoadedFromServer: boolean;
}
/** Returns information about the running dev server. */
export function getDevServer(): DevServerInfo;
// #endregion
// #region HMRClient
/** Client that receives Fast Refresh updates and applies them at runtime. */
export class HMRClient {
enable(): void;
disable(): void;
registerBundle(requestUrl: string): void;
log(
level:
| 'trace'
| 'info'
| 'warn'
| 'error'
| 'log'
| 'group'
| 'groupCollapsed'
| 'groupEnd'
| 'debug',
data: ReadonlyArray<unknown>,
): void;
setup(
platform: string,
bundleEntry: string,
host: string,
port: number | string,
isEnabled: boolean,
scheme?: string,
): void;
}
// #endregion
// #region NativeExceptionsManager
interface StackFrame {
column: number | null;
file: string | null;
lineNumber: number | null;
methodName: string;
collapse?: boolean | undefined;
}
interface ExceptionData {
message: string;
originalMessage: string | null;
name: string | null;
componentStack: string | null;
stack: StackFrame[];
id: number;
isFatal: boolean;
extraData?: object | undefined;
}
/** Reports JS exceptions to native and manages RedBox. */
export const NativeExceptionsManager: {
reportFatalException(
message: string,
stack: StackFrame[],
exceptionId: number,
): void;
reportSoftException(
message: string,
stack: StackFrame[],
exceptionId: number,
): void;
dismissRedbox(): void;
reportException(data: ExceptionData): void;
};
// #endregion
// #region NativeRedBox
interface NativeRedBoxSpec {
setExtraData(extraData: object, forIdentifier: string): void;
dismiss(): void;
}
/** Native module for the RedBox error overlay; null when unavailable. */
export const NativeRedBox: NativeRedBoxSpec | null;
// #endregion
// #region NativeSourceCode
interface SourceCodeConstants {
scriptURL: string;
}
/** Native module exposing source-code constants such as the bundle scriptURL. */
export const NativeSourceCode: {
getConstants(): SourceCodeConstants;
};
// #endregion
// #region PressabilityDebugView
type Rect = Readonly<{
bottom?: number | null | undefined;
left?: number | null | undefined;
right?: number | null | undefined;
top?: number | null | undefined;
}>;
type RectOrSize = Rect | number;
interface PressabilityDebugViewProps {
color: unknown;
hitSlop: RectOrSize | null | undefined;
}
/** Debug overlay that visualizes press targets when enabled via the Inspector. */
export const PressabilityDebugView: React.ComponentType<PressabilityDebugViewProps>;
// #endregion
@@ -0,0 +1,76 @@
/**
* 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.
*
* @noflow
* @format
*/
'use strict';
'use client';
// ----------------------------------------------------------------------------
// react-native/unstable-internals-do-not-use
//
// UNSTABLE WITH NO SEMVER GUARANTEES.
// SHOULD NOT BE DEPENDED ON BY NEW CODE.
//
// This is a secondary entry point for frameworks and libraries that depend on
// specific React Native internals, serving as a compatibility bridge.
//
// Consuming codebases must opt in via tsconfig.json:
// "customConditions": ["react-native-unstable-internals"]
//
// Having this entry point:
// - Maintains a known list of which React Native internals are in use.
// - Enables us to relocate supporting files more freely.
// - Gives us time to decide on the future of these APIs (independent from
// removal of the Strict API opt out).
//
// The long term future of these exports is to formalize/delete them where
// appropriate, and collapse this entry point.
//
// Replaces RFC0985
// https://github.com/react-native-community/discussions-and-proposals/pull/985
// where we reviewed internal APIs used in the ecosystem.
//
// IMPORTANT: Keep this file in sync with unstable-internals-do-not-use.d.ts.
// ----------------------------------------------------------------------------
// eslint-disable-next-line @react-native/monorepo/no-commonjs-exports
module.exports = {
get AppContainer() {
return require('../Libraries/ReactNative/AppContainer').default;
},
get AssetSourceResolver() {
return require('../Libraries/Image/AssetSourceResolver').default;
},
get customDirectEventTypes() {
return require('../Libraries/Renderer/shims/ReactNativeViewConfigRegistry')
.customDirectEventTypes;
},
get DevLoadingView() {
return require('../Libraries/Utilities/DevLoadingView').default;
},
get getDevServer() {
return require('../Libraries/Core/Devtools/getDevServer').default;
},
get HMRClient() {
return require('../Libraries/Utilities/HMRClient').default;
},
get NativeExceptionsManager() {
return require('../Libraries/Core/NativeExceptionsManager').default;
},
get NativeRedBox() {
return require('../Libraries/NativeModules/specs/NativeRedBox').default;
},
get NativeSourceCode() {
return require('../Libraries/NativeModules/specs/NativeSourceCode').default;
},
get PressabilityDebugView() {
return require('../Libraries/Pressability/PressabilityDebug')
.PressabilityDebugView;
},
};