react · j-piasecki · Sep 4, 2026
diff --git a/packages/react-native/ReactAndroid/build.gradle.kts b/packages/react-native/ReactAndroid/build.gradle.kts
@@ -227,6 +227,7 @@ val preparePrefab by
                       Pair("../ReactCommon/jserrorhandler/", "jserrorhandler/"),
                       Pair("../ReactCommon/react/bridging/", "react/bridging/"),
                       Pair("../ReactCommon/react/nativemodule/core/", ""),
+                      Pair("../ReactCommon/react/nativemodule/core/React/", "React/"),
                       Pair("../ReactCommon/react/nativemodule/core/platform/android/", ""),
                       Pair(
                           "../ReactCommon/react/renderer/componentregistry/",

diff --git a/packages/react-native/ReactCommon/ReactCommon.podspec b/packages/react-native/ReactCommon/ReactCommon.podspec
@@ -51,14 +51,22 @@ Pod::Spec.new do |s|
 
     ss.subspec "core" do |sss|
       sss.source_files = podspec_sources("react/nativemodule/core/ReactCommon/**/*.{cpp,h}", "react/nativemodule/core/ReactCommon/**/*.h")
-      sss.pod_target_xcconfig  = { "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/ReactCommon\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-debug/React_debug.framework/Headers\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-debug/React_featureflags.framework/Headers\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-utils/React_utils.framework/Headers\"" }
+      sss.pod_target_xcconfig  = { "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)\" \"$(PODS_TARGET_SRCROOT)/ReactCommon\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-debug/React_debug.framework/Headers\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-debug/React_featureflags.framework/Headers\" \"$(PODS_CONFIGURATION_BUILD_DIR)/React-utils/React_utils.framework/Headers\"" }
       sss.dependency "React-bridging"
       sss.dependency "React-cxxreact", version
       sss.dependency "React-debug", version
       sss.dependency "React-featureflags", version
       sss.dependency "React-utils", version
     end
+
+    ss.subspec "coreUmbrella" do |sss|
+      sss.source_files         = "react/nativemodule/core/React/*.h"
+      sss.header_dir           = ""
+      sss.header_mappings_dir  = "react/nativemodule/core"
+    end
   end
 
+  s.dependency "React-cxxstableapi"
+
   mark_as_react_native_build(s)
 end
diff --git a/packages/react-native/ReactCommon/react/nativemodule/core/CMakeLists.txt b/packages/react-native/ReactCommon/react/nativemodule/core/CMakeLists.txt
@@ -22,6 +22,7 @@ target_include_directories(react_nativemodule_core
           ${CMAKE_CURRENT_SOURCE_DIR}
           ${platform_DIR}
         )
+target_include_directories(react_nativemodule_core INTERFACE ${REACT_COMMON_DIR}/react/nativemodule/core)
 
 react_native_android_selector(fbjni fbjni "")
 react_native_android_selector(reactnativejni reactnativejni "")
@@ -31,6 +32,7 @@ target_link_libraries(react_nativemodule_core
         glog
         jsi
         react_bridging
+        react_cxxstableapi
         react_debug
         react_utils
         react_featureflags

diff --git a/packages/react-native/ReactCommon/react/nativemodule/core/React/NativeModuleCore.h b/packages/react-native/ReactCommon/react/nativemodule/core/React/NativeModuleCore.h
@@ -0,0 +1,43 @@
+/*
+ * 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.
+ */
+
+#pragma once
+
+// =============================================================================
+// Umbrella header for the `react/nativemodule/core` module - public entry
+// point.
+//
+//   #include <React/NativeModuleCore.h>
+//
+// Re-exports the module's public interface headers. React Native's own code
+// should keep using the fine-grained `<ReactCommon/...>` includes; only outside
+// consumers use this umbrella.
+// =============================================================================
+
+// Marks that the following headers are pulled in through the umbrella, so their
+// shared guard (<react/cxxstableapi/UmbrellaGuard.h>) accepts them. The marker
+// is saved and restored rather than defined and undefined: the scope ends at
+// this block, so later *direct* includes in the same TU are still caught, and
+// it nests inside an enclosing umbrella rather than disarming it.
+#pragma push_macro("RN_UMBRELLA_CONTEXT")
+#undef RN_UMBRELLA_CONTEXT
+#define RN_UMBRELLA_CONTEXT 1
+
+#include <ReactCommon/CxxTurboModuleUtils.h>
+#include <ReactCommon/TurboModule.h>
+#include <ReactCommon/TurboModuleBinding.h>
+#include <ReactCommon/TurboModulePerfLogger.h>
+#include <ReactCommon/TurboModuleUtils.h>
+#include <ReactCommon/TurboModuleWithJSIBindings.h>
+
+#ifdef ANDROID
+#include <ReactCommon/JavaInteropTurboModule.h>
+#include <ReactCommon/JavaTurboModule.h>
+#endif
+
+#undef RN_UMBRELLA_CONTEXT
+#pragma pop_macro("RN_UMBRELLA_CONTEXT")
diff --git a/packages/react-native/ReactCommon/react/nativemodule/core/ReactCommon/CxxTurboModuleUtils.h b/packages/react-native/ReactCommon/react/nativemodule/core/ReactCommon/CxxTurboModuleUtils.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <ReactCommon/CallInvoker.h>
 #include <ReactCommon/TurboModule.h>
 #include <functional>

diff --git a/packages/react-native/ReactCommon/react/nativemodule/core/ReactCommon/TurboModule.h b/packages/react-native/ReactCommon/react/nativemodule/core/ReactCommon/TurboModule.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <memory>
 #include <string>
 #include <unordered_map>

diff --git a/packages/react-native/ReactCommon/react/nativemodule/core/ReactCommon/TurboModuleBinding.h b/packages/react-native/ReactCommon/react/nativemodule/core/ReactCommon/TurboModuleBinding.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <string>
 
 #include <jsi/jsi.h>

diff --git a/...ages/react-native/ReactCommon/react/nativemodule/core/ReactCommon/TurboModulePerfLogger.h b/...ages/react-native/ReactCommon/react/nativemodule/core/ReactCommon/TurboModulePerfLogger.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <reactperflogger/NativeModulePerfLogger.h>
 #include <memory>
 

diff --git a/packages/react-native/ReactCommon/react/nativemodule/core/ReactCommon/TurboModuleUtils.h b/packages/react-native/ReactCommon/react/nativemodule/core/ReactCommon/TurboModuleUtils.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <jsi/jsi.h>
 #include <react/bridging/LongLivedObject.h>
 #include <cassert>

diff --git a/...react-native/ReactCommon/react/nativemodule/core/ReactCommon/TurboModuleWithJSIBindings.h b/...react-native/ReactCommon/react/nativemodule/core/ReactCommon/TurboModuleWithJSIBindings.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <ReactCommon/CallInvoker.h>
 #include <jsi/jsi.h>
 

diff --git a/...ReactCommon/react/nativemodule/core/platform/android/ReactCommon/JavaInteropTurboModule.h b/...ReactCommon/react/nativemodule/core/platform/android/ReactCommon/JavaInteropTurboModule.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #ifndef RCT_REMOVE_LEGACY_MODULE_INTEROP
 
 #include <string>

diff --git a/...native/ReactCommon/react/nativemodule/core/platform/android/ReactCommon/JavaTurboModule.h b/...native/ReactCommon/react/nativemodule/core/platform/android/ReactCommon/JavaTurboModule.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <string>
 
 #include <ReactCommon/CallInvoker.h>

diff --git a/packages/react-native/scripts/ios-prebuild/headers-config.js b/packages/react-native/scripts/ios-prebuild/headers-config.js
@@ -255,6 +255,11 @@ const PodspecExceptions /*: {[key: string]: PodSpecConfiguration} */ = {
         headerPatterns: ['react/nativemodule/core/ReactCommon/**/*.h'],
         headerDir: 'ReactCommon',
       },
+      {
+        name: 'coreUmbrella',
+        headerPatterns: ['react/nativemodule/core/React/*.h'],
+        headerDir: 'React',
+      },
     ],
   },