react · j-piasecki · Aug 28, 2026
diff --git a/packages/react-native/ReactAndroid/build.gradle.kts b/packages/react-native/ReactAndroid/build.gradle.kts
@@ -165,6 +165,7 @@ val preparePrefab by
                       Pair("../ReactCommon/react/renderer/uimanager/React/", "React/"),
                       // react_utils
                       Pair("../ReactCommon/react/utils/", "react/utils/"),
+                      Pair("../ReactCommon/react/utils/React/", "React/"),
                       // rrc_image
                       Pair(
                           "../ReactCommon/react/renderer/components/image/",

diff --git a/packages/react-native/ReactCommon/react/utils/Base64.h b/packages/react-native/ReactCommon/react/utils/Base64.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <string>
 #include <string_view>
 

diff --git a/packages/react-native/ReactCommon/react/utils/CMakeLists.txt b/packages/react-native/ReactCommon/react/utils/CMakeLists.txt
@@ -31,6 +31,7 @@ target_link_libraries(react_utils
         glog
         glog_init
         jsi
+        react_cxxstableapi
         react_debug)
 target_compile_reactnative_options(react_utils PRIVATE)
 target_compile_options(react_utils PRIVATE -Wpedantic)
diff --git a/packages/react-native/ReactCommon/react/utils/ContextContainer.h b/packages/react-native/ReactCommon/react/utils/ContextContainer.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <memory>
 #include <mutex>
 #include <optional>

diff --git a/packages/react-native/ReactCommon/react/utils/FloatComparison.h b/packages/react-native/ReactCommon/react/utils/FloatComparison.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <cmath>
 
 namespace facebook::react {

diff --git a/packages/react-native/ReactCommon/react/utils/MoveWrapper.h b/packages/react-native/ReactCommon/react/utils/MoveWrapper.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <memory>
 
 namespace facebook::react {

diff --git a/packages/react-native/ReactCommon/react/utils/OnScopeExit.h b/packages/react-native/ReactCommon/react/utils/OnScopeExit.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <utility>
 
 namespace facebook::react {

diff --git a/packages/react-native/ReactCommon/react/utils/PackTraits.h b/packages/react-native/ReactCommon/react/utils/PackTraits.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <type_traits>
 
 namespace facebook::react::traits {

diff --git a/packages/react-native/ReactCommon/react/utils/React-utils.podspec b/packages/react-native/ReactCommon/react/utils/React-utils.podspec
@@ -32,7 +32,7 @@ Pod::Spec.new do |s|
   s.source                 = source
   s.source_files           = podspec_sources(source_files, ["*.h", "platform/ios/**/*.h"])
   s.header_dir             = "react/utils"
-  s.exclude_files          = "tests"
+  s.exclude_files          = ["tests", "React"]
 
   if ENV['USE_FRAMEWORKS']
     header_search_paths = header_search_paths + ["\"$(PODS_TARGET_SRCROOT)/platform/ios\""]
@@ -46,6 +46,7 @@ Pod::Spec.new do |s|
                                "DEFINES_MODULE" => "YES" }
 
   s.dependency "React-jsi", version
+  s.dependency "React-cxxstableapi"
 
   if use_hermes()
     s.dependency "hermes-engine"
@@ -55,5 +56,11 @@ Pod::Spec.new do |s|
 
   add_dependency(s, "React-debug")
 
+  s.subspec "utilsUmbrella" do |ss|
+    ss.source_files        = "React/*.h"
+    ss.header_dir          = "React"
+    ss.header_mappings_dir = "React"
+  end
+
   mark_as_react_native_build(s)
 end
diff --git a/packages/react-native/ReactCommon/react/utils/React/Utils.h b/packages/react-native/ReactCommon/react/utils/React/Utils.h
@@ -0,0 +1,46 @@
+/*
+ * 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/utils` module - public entry point.
+//
+//   #include <React/Utils.h>
+//
+// Re-exports the module's public interface headers. React Native's own code
+// should keep using the fine-grained `<react/utils/...>` 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. Scoped to
+// this block so later *direct* includes in the same TU are still caught.
+#define RN_UMBRELLA_CONTEXT
+
+#include <react/utils/Base64.h>
+#include <react/utils/ContextContainer.h>
+#include <react/utils/FloatComparison.h>
+#include <react/utils/LowPriorityExecutor.h>
+#include <react/utils/ManagedObjectWrapper.h>
+#include <react/utils/MoveWrapper.h>
+#include <react/utils/OnScopeExit.h>
+#include <react/utils/PackTraits.h>
+#include <react/utils/RunLoopObserver.h>
+#include <react/utils/SharedFunction.h>
+#include <react/utils/SimpleThreadSafeCache.h>
+#include <react/utils/Telemetry.h>
+#include <react/utils/TemplateStringLiteral.h>
+#include <react/utils/Uuid.h>
+#include <react/utils/fnv1a.h>
+#include <react/utils/hash_combine.h>
+#include <react/utils/iequals.h>
+#include <react/utils/jsi-utils.h>
+#include <react/utils/toLower.h>
+#include <react/utils/to_underlying.h>
+
+#undef RN_UMBRELLA_CONTEXT
diff --git a/packages/react-native/ReactCommon/react/utils/RunLoopObserver.h b/packages/react-native/ReactCommon/react/utils/RunLoopObserver.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <atomic>
 #include <functional>
 #include <memory>

diff --git a/packages/react-native/ReactCommon/react/utils/SharedFunction.h b/packages/react-native/ReactCommon/react/utils/SharedFunction.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <functional>
 #include <memory>
 #include <mutex>

diff --git a/packages/react-native/ReactCommon/react/utils/SimpleThreadSafeCache.h b/packages/react-native/ReactCommon/react/utils/SimpleThreadSafeCache.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <concepts>
 #include <list>
 #include <mutex>

diff --git a/packages/react-native/ReactCommon/react/utils/Telemetry.h b/packages/react-native/ReactCommon/react/utils/Telemetry.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <chrono>
 #include <type_traits>
 

diff --git a/packages/react-native/ReactCommon/react/utils/TemplateStringLiteral.h b/packages/react-native/ReactCommon/react/utils/TemplateStringLiteral.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <algorithm>
 #include <array>
 #include <string_view>

diff --git a/packages/react-native/ReactCommon/react/utils/Uuid.h b/packages/react-native/ReactCommon/react/utils/Uuid.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <string>
 
 namespace facebook::react {

diff --git a/packages/react-native/ReactCommon/react/utils/fnv1a.h b/packages/react-native/ReactCommon/react/utils/fnv1a.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <cstdint>
 #include <functional>
 #include <string_view>

diff --git a/packages/react-native/ReactCommon/react/utils/hash_combine.h b/packages/react-native/ReactCommon/react/utils/hash_combine.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <functional>
 #include <type_traits>
 

diff --git a/packages/react-native/ReactCommon/react/utils/iequals.h b/packages/react-native/ReactCommon/react/utils/iequals.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <react/utils/toLower.h>
 #include <string_view>
 

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

diff --git a/...s/react-native/ReactCommon/react/utils/platform/android/react/utils/LowPriorityExecutor.h b/...s/react-native/ReactCommon/react/utils/platform/android/react/utils/LowPriorityExecutor.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 namespace facebook::react::LowPriorityExecutor {
 
 void execute(std::function<void()> &&workItem);

diff --git a/packages/react-native/ReactCommon/react/utils/platform/cxx/react/utils/LowPriorityExecutor.h b/packages/react-native/ReactCommon/react/utils/platform/cxx/react/utils/LowPriorityExecutor.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <functional>
 
 namespace facebook::react::LowPriorityExecutor {

diff --git a/packages/react-native/ReactCommon/react/utils/platform/ios/react/utils/LowPriorityExecutor.h b/packages/react-native/ReactCommon/react/utils/platform/ios/react/utils/LowPriorityExecutor.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <functional>
 
 namespace facebook::react::LowPriorityExecutor {

diff --git a/packages/react-native/ReactCommon/react/utils/toLower.h b/packages/react-native/ReactCommon/react/utils/toLower.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 namespace facebook::react {
 
 /**

diff --git a/packages/react-native/ReactCommon/react/utils/to_underlying.h b/packages/react-native/ReactCommon/react/utils/to_underlying.h
@@ -7,6 +7,8 @@
 
 #pragma once
 
+#include <react/cxxstableapi/UmbrellaGuard.h>
+
 #include <type_traits>
 
 namespace facebook::react {

diff --git a/packages/react-native/scripts/ios-prebuild/headers-config.js b/packages/react-native/scripts/ios-prebuild/headers-config.js
@@ -627,6 +627,24 @@ const PodspecExceptions /*: {[key: string]: PodSpecConfiguration} */ = {
   'Libraries/PushNotificationIOS/React-RCTPushNotification.podspec': {
     disabled: true,
   },
+  'ReactCommon/react/utils/React-utils.podspec': {
+    name: 'React-utils',
+    headerPatterns: [],
+    headerDir: '',
+    subSpecs: [
+      {
+        name: 'utils',
+        headerPatterns: ['*.h', 'platform/ios/**/*.h'],
+        excludePatterns: ['tests', 'React'],
+        headerDir: 'react/utils',
+      },
+      {
+        name: 'utilsUmbrella',
+        headerPatterns: ['React/*.h'],
+        headerDir: 'React',
+      },
+    ],
+  },
 };
 
 module.exports = {PodspecExceptions};
-Original file line number
+Diff line change
@@ Expand Up / @@ -7,6 +7,8 @@ @@
     #pragma once
+    #include <react/cxxstableapi/UmbrellaGuard.h>
     namespace facebook::react {
     /**
@@ Expand Down @@