refactor(spm): replace VFS overlay with a materialized merged header tree

Consuming Package.swift manifests previously re-derived a block of header
config (locate React.xcframework, resolve its cache-slot symlink, compute
xcfwHeaders/depsHeaders, reference a per-app React-VFS.yaml overlay, and pass
-ivfsoverlay + several -I per target). This duplicated fragile path logic
across every generated, scaffolded, and hand-authored manifest.

Materialize a single natural-layout merged header tree
(build/xcframeworks/ReactHeadersAll) at spm setup/sync time and have every
consumer reference it with one `-I`. The tree is built by reusing the
React-VFS-template.yaml already shipped in React.xcframework, with the
ReactNativeDependencies, codegen, and autolinking headers folded in. One
canonical file per import path means a single header identity, so the VFS
overlay is no longer needed for SPM.

- spm-utils.js: add buildMergedHeaderTree() + shared rnHeaders flag helpers;
  remove resolveAndWriteVFSOverlay() and the codegen slot-path baking.
- generate-spm-autolinking.js / scaffold-package-swift.js / the codegen
  Package.swift template: emit a single `-I rnHeaders` (+ -fno-implicit-module-maps
  for the clang library targets) instead of the VFS overlay.
- generate-spm-xcodeproj.js: wire the app target to the merged tree for the
  `import React` path (no -fno-implicit-module-maps here — it breaks SDK
  module resolution); drop the Prepare VFS Overlay phase.
- setup-apple-spm.js / sync-spm-autolinking.js: build the tree where the VFS
  overlay was resolved before.

CocoaPods and the xcframework build are untouched. Verified by building
rn-tester (package-root layout) and helloworld (template layout), plus the
SPM jest suite.

Author: chrfalch

packages/react-native/scripts/codegen/templates/Package.swift.spm-template

@@ -16,14 +16,11 @@ import Foundation
 // Derive all paths from this file's location.
 let packageDir = URL(fileURLWithPath: #filePath).deletingLastPathComponent().path
 let appRoot = URL(fileURLWithPath: packageDir + "/../../..").standardized.path
-// xcfwHeaders / depsHeaders: when the install step resolves the current
-// cache-slot symlinks, the placeholders below are replaced with absolute
-// string literals so SPM's manifest hash bumps on every slot change
-// (otherwise the cached `.resolvingSymlinksInPath()` value would stick on
-// the prior slot). Unsubstituted, falls back to the runtime expression.
-let xcfwHeaders = __SPM_XCFW_HEADERS_EXPR__
-let depsHeaders = __SPM_DEPS_HEADERS_EXPR__
-let vfsOverlay = appRoot + "/build/xcframeworks/React-VFS.yaml"
+// Single natural-layout merged header tree (React + deps + codegen +
+// autolinking), materialized at setup/sync time by buildMergedHeaderTree. The
+// path is stable across cache slots — only the symlink contents change — so the
+// manifest hash never churns.
+let rnHeaders = appRoot + "/build/xcframeworks/ReactHeadersAll"
 
 let package = Package(
     name: "React-GeneratedCode",
@@ -51,15 +48,15 @@ let package = Package(
             publicHeadersPath: ".",
             cSettings: [
                 .headerSearchPath("headers"),
-                .unsafeFlags(["-ivfsoverlay", vfsOverlay, "-I", xcfwHeaders]),
+                .unsafeFlags(["-I", rnHeaders]),
             ],
             cxxSettings: [
                 .headerSearchPath("headers"),
                 .unsafeFlags(["-std=c++20"]),
                 // -fno-implicit-module-maps prevents clang from matching <react/...> to
                 // React.framework (case-insensitive) in the build products dir, allowing
-                // -I and VFS overlay to resolve C++ headers correctly.
-                .unsafeFlags(["-fno-implicit-module-maps", "-ivfsoverlay", vfsOverlay, "-I", xcfwHeaders, "-I", depsHeaders]),
+                // -I to resolve the C++ headers from the merged tree correctly.
+                .unsafeFlags(["-fno-implicit-module-maps", "-I", rnHeaders]),
             ],
             linkerSettings: [
                 .linkedFramework("Foundation")
@@ -74,13 +71,13 @@ let package = Package(
             cSettings: [
                 .headerSearchPath(".."),
                 .headerSearchPath("headers"),
-                .unsafeFlags(["-ivfsoverlay", vfsOverlay, "-I", xcfwHeaders]),
+                .unsafeFlags(["-I", rnHeaders]),
             ],
             cxxSettings: [
                 .headerSearchPath(".."),
                 .headerSearchPath("headers"),
                 .unsafeFlags(["-std=c++20"]),
-                .unsafeFlags(["-fno-implicit-module-maps", "-ivfsoverlay", vfsOverlay, "-I", xcfwHeaders, "-I", depsHeaders]),
+                .unsafeFlags(["-fno-implicit-module-maps", "-I", rnHeaders]),
             ],
             linkerSettings: [
                 .linkedFramework("Foundation")

packages/react-native/scripts/setup-apple-spm.js

@@ -94,14 +94,14 @@ const {
 } = require('./spm/generate-spm-xcodeproj');
 const {scaffoldAll} = require('./spm/scaffold-package-swift');
 const {
+  buildMergedHeaderTree,
   defaultCacheDir,
   deriveAppName,
   displayPath,
   findProjectRoot,
   installSpmCodegenTemplate,
   makeLogger,
   readPackageJson,
-  resolveAndWriteVFSOverlay,
   runCodegenAndInstallTemplate,
 } = require('./spm/spm-utils');
 const fs = require('fs');
@@ -1510,16 +1510,12 @@ async function main(argv /*:: ?: Array<string> */) /*: Promise<void> */ {
     return;
   }
 
-  // Re-install the codegen Package.swift template AFTER the xcframework
-  // symlinks have been created. The earlier install (during runCodegenStep)
-  // hits resolveHeadersAbsolute's catch block because the symlinks don't
-  // exist yet — the template falls back to a runtime URL expression. SPM
-  // caches that manifest evaluation and never re-resolves on slot changes,
-  // so a stale slot path leaks into compile args. Re-installing now bakes
-  // the absolute path in, changing the manifest content and the SPM hash.
+  // (Re)install the static codegen Package.swift template once build/generated/ios exists.
   installSpmCodegenTemplate(appRoot, reactNativeRoot, {log});
 
-  resolveAndWriteVFSOverlay(appRoot, reactNativeRoot, {log});
+  // Materialize the merged header tree (replaces the VFS overlay). Runs last:
+  // it folds in the xcframework, codegen, and autolinking headers.
+  buildMergedHeaderTree(appRoot, {log});
 
   let migrationRename /*: {from: string, to: string} | null */ = null;
   if (action === 'init') {

packages/react-native/scripts/spm/__tests__/generate-spm-autolinking-test.js

@@ -83,8 +83,10 @@ describe('generateAutolinkedPackageSwift (aggregator)', () => {
     expect(result).toMatch(
       /name: "ScreenshotManager",[\s\S]*?\.product\(name: "ReactNative", package: "ReactNative"\)/,
     );
-    // Inline target gets cFlags / linker frameworks
-    expect(result).toContain('-ivfsoverlay');
+    // Inline target gets the merged-header include + linker frameworks, and no
+    // legacy VFS overlay flag.
+    expect(result).toContain('"-I", rnHeaders');
+    expect(result).not.toContain('-ivfsoverlay');
     expect(result).toContain('.linkedFramework("CoreGraphics")');
   });
 
@@ -182,20 +184,25 @@ describe('generateSynthPackageSwift', () => {
     );
   });
 
-  it('embeds xcfwHeaders / vfsOverlay flags when hasXcfwHeaders is true', () => {
+  it('emits a single -I into the merged header tree when hasXcfwHeaders is true', () => {
     const result = generateSynthPackageSwift(baseSpec({hasXcfwHeaders: true}));
-    expect(result).toContain('let xcfwHeaders');
-    expect(result).toContain('let vfsOverlay');
-    expect(result).toContain('"-ivfsoverlay"');
-    expect(result).toContain('"-I", xcfwHeaders');
+    expect(result).toContain(
+      'let rnHeaders = appRoot + "/build/xcframeworks/ReactHeadersAll"',
+    );
+    expect(result).toContain('"-I", rnHeaders');
+    // The legacy VFS overlay + per-framework derivation is gone.
+    expect(result).not.toContain('-ivfsoverlay');
+    expect(result).not.toContain('let xcfwHeaders');
+    expect(result).not.toContain('let vfsOverlay');
   });
 
-  it('adds depsHeaders -I to cxxSettings only when hasDepsHeaders is true', () => {
+  it('covers deps/codegen via the single merged tree (no separate depsHeaders -I)', () => {
     const result = generateSynthPackageSwift(
       baseSpec({hasXcfwHeaders: true, hasDepsHeaders: true}),
     );
-    expect(result).toContain('let depsHeaders');
-    expect(result).toContain('"-I", depsHeaders');
+    expect(result).toContain('"-I", rnHeaders');
+    expect(result).not.toContain('let depsHeaders');
+    expect(result).not.toContain('"-I", depsHeaders');
   });
 
   it('emits exclude list when given', () => {
@@ -295,7 +302,7 @@ describe('generateSynthPackageSwift', () => {
     expect(result).toContain('path: "root"');
   });
 
-  it('wrapper-dir mode: autogenHeadersAbsolute adds -I to cSettings + cxxSettings (replaces publicHeadersPath)', () => {
+  it('wrapper-dir mode: routes all includes through the single merged tree (autolinking headers folded in)', () => {
     const result = generateSynthPackageSwift({
       swiftName: 'MyDep',
       hasReactDep: true,
@@ -304,14 +311,12 @@ describe('generateSynthPackageSwift', () => {
       appRootAbsolute: '/abs/app',
       autogenHeadersAbsolute: '/abs/app/build/generated/autolinking/headers',
     });
-    expect(result).toContain(
+    // The autolinking headers dir is folded into ReactHeadersAll, so it is no
+    // longer a separate -I; only the merged tree include remains.
+    expect(result).toContain('"-I", rnHeaders');
+    expect(result).not.toContain(
       '"-I", "/abs/app/build/generated/autolinking/headers"',
     );
-    // The -I appears in both cSettings (Obj-C .m) and cxxSettings (.mm/.cpp).
-    const matches = result.match(
-      /"-I", "\/abs\/app\/build\/generated\/autolinking\/headers"/g,
-    );
-    expect(matches && matches.length).toBeGreaterThanOrEqual(2);
   });
 
   it('wrapper-dir mode: omits publicHeadersPath (headers route through -I instead)', () => {

packages/react-native/scripts/spm/__tests__/generate-spm-xcodeproj-test.js

@@ -110,11 +110,12 @@ describe('generatePbxproj', () => {
     expect(result).toContain('Sync SPM Autolinking');
     expect(result).toContain('npx react-native spm sync');
     expect(result).toContain('Build JS Bundle');
-    expect(result).toContain('Prepare VFS Overlay');
-    // Sync must run before VFS overlay
+    // No VFS overlay phase anymore — headers come from the merged tree.
+    expect(result).not.toContain('Prepare VFS Overlay');
+    // Sync must run before the JS bundle phase.
     const syncIdx = result.indexOf('Sync SPM Autolinking');
-    const vfsIdx = result.indexOf('Prepare VFS Overlay');
-    expect(syncIdx).toBeLessThan(vfsIdx);
+    const bundleIdx = result.indexOf('Build JS Bundle');
+    expect(syncIdx).toBeLessThan(bundleIdx);
   });
 
   it('sync script checks workspace lockfiles and hoisted node_modules', () => {

packages/react-native/scripts/spm/__tests__/spm-utils-test.js

@@ -11,6 +11,7 @@
 'use strict';
 
 const {
+  buildMergedHeaderTree,
   defaultCacheDir,
   displayPath,
   makeLogger,
@@ -288,3 +289,164 @@ describe('runCodegenAndInstallTemplate', () => {
     expect(fs.existsSync(codegenPkgSwift)).toBe(false);
   });
 });
+
+// ---------------------------------------------------------------------------
+// buildMergedHeaderTree
+// ---------------------------------------------------------------------------
+describe('buildMergedHeaderTree', () => {
+  let tempDir;
+  let appRoot;
+  let xcfwDir;
+  let outDir;
+
+  function writeFile(p, contents) {
+    fs.mkdirSync(path.dirname(p), {recursive: true});
+    fs.writeFileSync(p, contents);
+  }
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'spm-merged-test-'));
+    appRoot = path.join(tempDir, 'app');
+    xcfwDir = path.join(appRoot, 'build', 'xcframeworks');
+    outDir = path.join(xcfwDir, 'ReactHeadersAll');
+
+    const reactXcfw = path.join(xcfwDir, 'React.xcframework');
+    // Namespaced physical React headers (as shipped in the xcframework).
+    writeFile(
+      path.join(reactXcfw, 'Headers', 'React_Fabric', 'react', 'foo', 'Bar.h'),
+      '#pragma once\n// react Bar\n',
+    );
+    // React_RCTAppDelegate headers — host apps import these BARE, so they must
+    // also surface at the merged-tree root.
+    writeFile(
+      path.join(
+        reactXcfw,
+        'Headers',
+        'React_RCTAppDelegate',
+        'RCTDefaultReactNativeFactoryDelegate.h',
+      ),
+      '#pragma once\n// app delegate\n',
+    );
+    // VFS template mapping the virtual <react/foo/Bar.h> to that physical file.
+    writeFile(
+      path.join(reactXcfw, 'React-VFS-template.yaml'),
+      [
+        'version: 0',
+        "case-sensitive: false",
+        'roots:',
+        "  - name: '${ROOT_PATH}/Headers'",
+        "    type: 'directory'",
+        "    contents:",
+        "      - name: 'react'",
+        "        type: 'directory'",
+        "        contents:",
+        "          - name: 'foo'",
+        "            type: 'directory'",
+        "            contents:",
+        "              - name: 'Bar.h'",
+        "                type: 'file'",
+        "                external-contents: '${ROOT_PATH}/Headers/React_Fabric/react/foo/Bar.h'",
+        '',
+      ].join('\n'),
+    );
+    // Deps headers (natural layout, folded in).
+    writeFile(
+      path.join(
+        xcfwDir,
+        'ReactNativeDependencies.xcframework',
+        'Headers',
+        'folly',
+        'dynamic.h',
+      ),
+      '#pragma once\n// folly\n',
+    );
+    // Autolinking header farm — a SYMLINK farm (leaf headers are symlinks to
+    // the dep's real source). foldDir must follow symlinks, not skip them.
+    const realProviderHeader = path.join(tempDir, 'src', 'Provider.h');
+    writeFile(realProviderHeader, '#pragma once\n// provider\n');
+    const farmHeader = path.join(
+      appRoot,
+      'build',
+      'generated',
+      'autolinking',
+      'headers',
+      'MyLib',
+      'Provider.h',
+    );
+    fs.mkdirSync(path.dirname(farmHeader), {recursive: true});
+    fs.symlinkSync(realProviderHeader, farmHeader);
+    // Codegen header (folded in) + a duplicate of the React virtual path with
+    // DIFFERENT content, to prove React (folded first) wins.
+    writeFile(
+      path.join(
+        appRoot,
+        'build',
+        'generated',
+        'ios',
+        'ReactCodegen',
+        'react',
+        'renderer',
+        'EventEmitters.h',
+      ),
+      '#pragma once\n// codegen\n',
+    );
+    writeFile(
+      path.join(appRoot, 'build', 'generated', 'ios', 'react', 'foo', 'Bar.h'),
+      '#pragma once\n// codegen Bar (should NOT win)\n',
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, {recursive: true, force: true});
+  });
+
+  it('materializes a merged tree of symlinks from the VFS template + folded dirs', () => {
+    const result = buildMergedHeaderTree(appRoot);
+    expect(result).toBe(outDir);
+
+    const reactHeader = path.join(outDir, 'react', 'foo', 'Bar.h');
+    const follyHeader = path.join(outDir, 'folly', 'dynamic.h');
+    const codegenHeader = path.join(
+      outDir,
+      'react',
+      'renderer',
+      'EventEmitters.h',
+    );
+    // React header resolves via its natural import path...
+    expect(fs.existsSync(reactHeader)).toBe(true);
+    expect(fs.lstatSync(reactHeader).isSymbolicLink()).toBe(true);
+    // ...and deps + codegen headers are folded into the same tree.
+    expect(fs.existsSync(follyHeader)).toBe(true);
+    expect(fs.existsSync(codegenHeader)).toBe(true);
+    // ...including the symlinked autolinking-farm header (foldDir follows symlinks).
+    expect(fs.existsSync(path.join(outDir, 'MyLib', 'Provider.h'))).toBe(true);
+  });
+
+  it('exposes React_RCTAppDelegate headers BARE at the root (host apps import them unprefixed)', () => {
+    buildMergedHeaderTree(appRoot);
+    // bare — what `#import <RCTDefaultReactNativeFactoryDelegate.h>` needs.
+    expect(
+      fs.existsSync(path.join(outDir, 'RCTDefaultReactNativeFactoryDelegate.h')),
+    ).toBe(true);
+  });
+
+  it('collapses a duplicate virtual path to the first (React) source', () => {
+    buildMergedHeaderTree(appRoot);
+    // build/generated/ios also has react/foo/Bar.h, but React is folded first,
+    // so the merged entry must resolve to the React copy.
+    const merged = fs.readFileSync(
+      path.join(outDir, 'react', 'foo', 'Bar.h'),
+      'utf8',
+    );
+    expect(merged).toContain('react Bar');
+    expect(merged).not.toContain('should NOT win');
+  });
+
+  it('returns null when the xcframework is absent', () => {
+    fs.rmSync(path.join(xcfwDir, 'React.xcframework'), {
+      recursive: true,
+      force: true,
+    });
+    expect(buildMergedHeaderTree(appRoot)).toBe(null);
+  });
+});