Derive an SPM library's Swift name from its podspec, and give SwiftPM config a home

An autolinked library's SwiftPM target name is also its header import prefix,
so deriving it from the npm package name was wrong for most of the ecosystem
(react-native-svg publishes RNSVG, not ReactNativeSvg) and wrong silently — no
error, just headers nobody can import under the expected name.

A package's SwiftPM settings now live in `swiftpmConfig` in its package.json,
following codegenConfig's conventions: `name`, `dependencies`,
`autolinkingPlugin` and `scaffold` for a library, `modules` and `denyPlugins`
for an app. The `spm` block in react-native.config.js is deprecated — still
read, so nothing breaks, but it warns once per file and package.json wins field
by field.

A name resolves from `swiftpmConfig.name`, then the deprecated `spm.name`, then
the podspec's `header_dir` or name, then the npm name. The podspec is thereby
transitional rather than permanent: `spm scaffold` records the name it derived
as `swiftpmConfig.name` in the library's package.json, so the next run needs no
podspec to name it. It never overwrites a name the library already declares,
never records a name guessed from the npm name, and reports what it did.

A prefix Swift cannot spell is normalized to the identifier SwiftPM would
compile it as, with a warning. A reserved name or two deps landing on one name
is a hard error naming swiftpmConfig.name as the fix; the scope-borrowing that
auto-corrected collisions is removed, since a name the build invents is a name
no #import can predict. Collision checks key on SwiftPM's c99 name, so
react-native-svg and react_native_svg no longer pass and then compile as one
module.

Name resolution reads the two podspec fields it needs with the regex parser, so
it adds no `pod ipc spec` spawn, and the full read is memoized on the resolved
path so one run reads a podspec once across name resolution, header search paths
and scaffolding.

rn-tester and the Apple test library move to the new location.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: chrfalch

packages/react-native-test-library/apple/package.json

@@ -27,5 +27,10 @@
   "peerDependencies": {
     "react": "*",
     "react-native": "1000.0.0"
+  },
+  "swiftpmConfig": {
+    "dependencies": [
+      "react-native-test-library-common"
+    ]
   }
 }

packages/react-native-test-library/apple/react-native.config.js

@@ -16,7 +16,4 @@ module.exports = {
       ios: {},
     },
   },
-  spm: {
-    dependencies: ['react-native-test-library-common'],
-  },
 };

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

@@ -490,15 +490,27 @@ async function runScaffold(
 
   if (written.length > 0) {
     log(`Scaffolded Package.swift for ${written.length} dep(s):`);
+    // Silent for the outcomes that changed nothing ('already-set', 'skipped').
+    const nameOutcome = (outcome /*: ?string */) /*: string */ => {
+      if (outcome === 'created' || outcome === 'inserted') {
+        return " — also recorded 'swiftpmConfig.name' in its package.json";
+      }
+      if (outcome === 'failed') {
+        return " — could NOT record 'swiftpmConfig.name'; the manifest is written, the name is not";
+      }
+      return '';
+    };
     for (const r of written) {
-      log(`  • ${r.depName}`);
+      log(`  • ${r.depName}${nameOutcome(r.swiftpmName)}`);
     }
     log('');
     log(
       'node_modules is NOT committed and is wiped by `npm install`. To keep\n' +
         'these manifests, create and commit a patch with a tool like patch-package:\n' +
         '  • `npx patch-package <dep>` for each scaffolded dep, then commit the patch.\n' +
-        'Also consider asking the maintainer to ship a Package.swift upstream.\n' +
+        'The patch also captures any recorded `swiftpmConfig.name`, which is what\n' +
+        'lets the library be named without reading its podspec. Better still, ask the\n' +
+        'maintainer to ship both upstream.\n' +
         'Without a committed patch the build will hard-error again after a fresh install.',
     );
     log('');

packages/react-native/scripts/spm/__docs__/spm-autolinking-plugins.md

@@ -12,8 +12,8 @@ generates. See [spm-scripts.md](./spm-scripts.md) for the base tool.
 
 The documented extension points don't cover a framework:
 
-- `spm.modules` in `react-native.config.js` is a **static** list of simple
-  source modules. A framework discovers its modules **dynamically** (scanning
+- `swiftpmConfig.modules` in package.json is a **static** list of simple source
+  modules. A framework discovers its modules **dynamically** (scanning
   `node_modules`), generates a **module registry**, and ships mixed
   Swift/ObjC/C++ modules (e.g. `ExpoModulesCore`) that `spm scaffold` can't
   handle.
@@ -32,28 +32,28 @@ stale.
 
 ## Discovery — transitive, zero app config
 
-A dependency opts in from its **own** `react-native.config.js`, so installing
-the framework is enough (mirrors how CocoaPods pulls in `use_expo_modules!`
-transitively):
+A dependency opts in from its **own** package.json, so installing the framework
+is enough (mirrors how CocoaPods pulls in `use_expo_modules!` transitively):
 
-```js
-// node_modules/expo/react-native.config.js
-module.exports = {
-  spm: {autolinkingPlugin: './spm/autolinking-plugin.js'},
-};
+```json
+// node_modules/expo/package.json
+{
+  "swiftpmConfig": {"autolinkingPlugin": "./spm/autolinking-plugin.js"}
+}
 ```
 
-The autolinker already walks every dependency's `react-native.config.js`; any
-that declares `spm.autolinkingPlugin` is `require`d and invoked. No app-level
-registration or allowlist is required.
+The autolinker reads every dependency's SwiftPM settings; any that declares
+`autolinkingPlugin` is `require`d and invoked. No app-level registration or
+allowlist is required. The deprecated `spm.autolinkingPlugin` in
+`react-native.config.js` is still read — see
+[Migrating from react-native.config.js](spm-scripts.md#where-swiftpm-settings-live).
 
-**Opt-out escape hatch.** An app can exclude a plugin from its own
-`react-native.config.js`:
+**Opt-out escape hatch.** An app can exclude a plugin from its own package.json:
 
-```js
-module.exports = {
-  spm: {denyPlugins: ['some-framework']}, // npm names to skip
-};
+```json
+{
+  "swiftpmConfig": {"denyPlugins": ["some-framework"]}
+}
 ```
 
 ## The contract

packages/react-native/scripts/spm/__docs__/spm-scripts.md

@@ -331,49 +331,110 @@ build phase calls — a fine trade for not having to remember a command.
 
 ## Local Native Modules
 
-Modules not discovered via autolinking can be declared in
-`react-native.config.js`:
+Modules not discovered via autolinking are declared in the app's package.json.
+Each `path` is relative to the file that declares it — the project root for a
+package.json there, the Xcode project directory for a config kept there:
 
-```js
-module.exports = {
-  spm: {
-    modules: [
+```json
+{
+  "swiftpmConfig": {
+    "modules": [
       {
-        name: 'MyNativeModule',
-        path: 'ios/MyNativeModule', // relative to app root
-        exclude: ['*.podspec'], // optional
-      },
-    ],
-  },
-};
+        "name": "MyNativeModule",
+        "path": "ios/MyNativeModule",
+        "exclude": ["*.podspec"]
+      }
+    ]
+  }
+}
 ```
 
 Each entry becomes a target in `build/generated/autolinking/Package.swift`.
 Sources outside `build/generated/autolinking/` are automatically mirrored with
 file-level symlinks.
 
+## Where SwiftPM settings live
+
+A package's SwiftPM settings live under `swiftpmConfig` in its **package.json**,
+alongside `codegenConfig`.
+
+| Field               | Set by  | What it does                                                |
+| ------------------- | ------- | ----------------------------------------------------------- |
+| `name`              | library | Its SwiftPM target name, and so its header import prefix    |
+| `dependencies`      | library | npm names of native libraries it builds against             |
+| `autolinkingPlugin` | library | Path to an [autolinking plugin](spm-autolinking-plugins.md) |
+| `scaffold`          | library | `false` opts the library out of `spm scaffold`              |
+| `modules`           | app     | [Local native modules](#local-native-modules) to build      |
+| `denyPlugins`       | app     | npm names whose autolinking plugin to skip                  |
+
+```json
+{
+  "swiftpmConfig": {
+    "name": "RNSVG",
+    "dependencies": ["react-native-worklets"]
+  }
+}
+```
+
+A library's settings come from its own package.json. An **app's** are resolved
+field by field, each from the directory holding its package.json — the JS root,
+where codegen reads `codegenConfig` — falling back to the Xcode project
+directory. An unrecognised field is ignored with a warning naming it, so a typo
+does not pass silently.
+
+These settings used to live in an `spm` block in `react-native.config.js`. That
+block is **deprecated** but still read, with the same field names, so nothing
+breaks: move the keys across as they are, and package.json wins field by field.
+`npx react-native spm scaffold` writes the `name` for you — see
+[Community packages without a Package.swift](#community-packages-without-a-packageswift).
+
+## Library names
+
+An autolinked library's SwiftPM target name is also the prefix its headers are
+imported under (`#import <RNSVG/…>`), so it is not cosmetic: it has to be the
+prefix the library's own sources and its dependents already use.
+
+It is resolved in this order:
+
+1. `swiftpmConfig.name` in the library's package.json
+2. `spm.name` in `react-native.config.js` (deprecated)
+3. podspec `header_dir` — `React-Core` → `React`
+4. podspec name — `react-native-svg` → `RNSVG`
+5. npm package name — `react-native-svg` → `ReactNativeSvg`
+
+The podspec is transitional, `header_dir` first because that is what a library
+sets when its import prefix differs from its pod name; an unreadable one falls
+through rather than failing the build. A prefix Swift cannot spell is normalized
+— `Some.Pod` becomes `Some_Pod`, what SwiftPM would compile it as anyway — with
+a warning naming `swiftpmConfig.name`.
+
+Two names are refused outright: one React Native reserves (`ReactNative`,
+`ReactHeaders`, `ReactNativeHeaders`, `ReactNativeDependenciesHeaders`,
+`ReactAppHeaders`, `React-GeneratedCode`, `ReactCodegen`,
+`ReactAppDependencyProvider`, `Autolinked`), and one another library already
+took. Both are **hard errors** naming `swiftpmConfig.name` — nothing is renamed
+automatically, because a name the build invented is one no `#import` in your
+sources can predict. Two names must differ by more than case or punctuation to
+be two targets: `worklets` and `Worklets` share a headers directory, and
+`foo-bar` and `foo_bar` are one module, since SwiftPM replaces every character
+C99 rejects with `_`.
+
 ## Dependencies between libraries
 
 SwiftPM has no equivalent of a podspec's `s.dependency`, so a library that needs
-another native library declares it explicitly with `spm.dependencies` in its
-**own** `react-native.config.js` — a list of npm names:
+another native library declares it explicitly in its **own** package.json — a
+list of npm names:
 
-```js
-// react-native-reanimated/react-native.config.js
-module.exports = {
-  dependency: {platforms: {ios: {}}},
-  spm: {dependencies: ['react-native-worklets']},
-};
+```json
+// react-native-reanimated/package.json
+{
+  "swiftpmConfig": {"dependencies": ["react-native-worklets"]}
+}
 ```
 
-The autolinker starts from the directly-autolinked deps, follows each one's
-`spm.dependencies` **recursively**, and dedupes the result, so a transitive
-dependency is pulled into the package graph even when the app never depends on
-it directly. Declared names are mapped to Swift target names, so the dependent
-library's target can import it.
-
-This is a **library-author** surface, like the podspec dependency it replaces —
-apps don't normally set it.
+The autolinker follows these **recursively** from the directly-autolinked deps
+and dedupes, so a transitive dependency joins the package graph even when the
+app never depends on it directly.
 
 ### Config module format
 
@@ -385,11 +446,11 @@ an async one that takes only the default export. For maximum compatibility,
 prefer the one-line CommonJS form:
 
 ```js
-module.exports = {dependency: {platforms: {ios: {}}}, spm: {name: 'worklets'}};
+module.exports = {dependency: {platforms: {ios: {}}}};
 ```
 
-If the config fails to load, a warning names the file and the reason — the `spm`
-settings in it are ignored rather than silently applied.
+If the config fails to load, a warning names the file and the reason — any
+deprecated `spm` settings in it are ignored rather than silently applied.
 
 ## Self-managed community packages
 
@@ -427,7 +488,12 @@ npx react-native spm               # then inject/update as usual
 does not inject into the `.xcodeproj` — so on a first-time setup you still
 follow it with `npx react-native spm`.)
 
-Because `node_modules/` isn't committed, persist it so it survives the next
+`scaffold` also records the name it derived from the podspec as
+`swiftpmConfig.name` in the library's package.json — the one step that lets the
+library be named without reading a podspec at all. It never overwrites a name
+the library already declares, and it says which packages it edited.
+
+Because `node_modules/` isn't committed, persist both so they survive the next
 install:
 
 ```bash
@@ -445,7 +511,9 @@ workaround keeps your app building.
 > A library whose sources mix Swift **and** Objective-C/C++ in one target, or
 > that ships neither a `Package.swift` nor a podspec, can't be scaffolded
 > automatically — the error says so. Opt it out via `react-native.config.js`
-> (`platforms.ios = null`) or ask the maintainer for a prebuilt xcframework.
+> (`platforms.ios = null`) or ask the maintainer for a prebuilt xcframework. A
+> library can also opt out of scaffolding alone with
+> `"swiftpmConfig": {"scaffold": false}`.
 
 ## Framework plugins (Preview)
 
@@ -490,6 +558,7 @@ across apps; refresh it with `react-native spm update --download force`.
 | `spm add` fails: "no .xcodeproj found"                                                                                 | Create an app first (`npx @react-native-community/cli init`) or make a project in Xcode, then `spm add`.                                                                                                                                                                                                                                                    |
 | `spm add` fails: "multiple .xcodeproj found"                                                                           | Pass `--xcodeproj <path>` (and `--product-name <target>` if multiple app targets).                                                                                                                                                                                                                                                                          |
 | `Package.swift is missing for library "<name>"` (exit 2)                                                               | The dep ships no SwiftPM support. `npx react-native spm scaffold`, then re-run setup; persist with `patch-package`. See [Community packages without a Package.swift](#community-packages-without-a-packageswift)                                                                                                                                            |
+| `SPM Swift name collision`                                                                                             | Two libraries resolved to one Swift name, or one took a name React Native reserves. Set `swiftpmConfig.name` in the library's package.json — see [Library names](#library-names)                                                                                                                                                                            |
 | Missing headers                                                                                                        | Re-run `react-native spm`                                                                                                                                                                                                                                                                                                                                   |
 | "not contained in target"                                                                                              | Re-run setup (regenerates file-level symlinks)                                                                                                                                                                                                                                                                                                              |
 | Codegen fails                                                                                                          | Use `--skipCodegen` to iterate on other parts                                                                                                                                                                                                                                                                                                               |
@@ -596,7 +665,7 @@ _existing_ set of generated packages current; they do not create the first one.
 1. Compares timestamps of staleness inputs against
    `build/generated/autolinking/.spm-sync-stamp`:
    - `package.json` — dependency declarations
-   - `react-native.config.js` — `spm.modules` config
+   - `react-native.config.js` — autolinking config
    - `node_modules/` directory mtime — updated by any package manager (npm,
      yarn, pnpm, bun); also checks parent `node_modules` for monorepo setups
    - a missing `build/xcframeworks/` (e.g. after a manual clean) also marks

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

@@ -34,48 +34,77 @@ describe('discoverPlugins', () => {
     return {name, root};
   }
 
-  // readConfig fake: a dep opts in when opted[name] is truthy.
+  // A dep opts in through its package.json; `noConfig` stands in for the
+  // react-native.config.js the caller loads (absent for these cases).
+  const declarePlugin = dep =>
+    fs.writeFileSync(
+      path.join(dep.root, 'package.json'),
+      JSON.stringify({
+        name: dep.name,
+        swiftpmConfig: {autolinkingPlugin: './plugin.js'},
+      }),
+    );
+  const noConfig = () => null;
+
+  // The deprecated home, which Expo still ships.
   const readConfigFor = opted => root => {
     const name = path.basename(root);
     return opted[name] ? {spm: {autolinkingPlugin: './plugin.js'}} : null;
   };
 
-  it('discovers a plugin declared via react-native.config.js', () => {
+  it('discovers a plugin declared in package.json', () => {
     const dep = makeDep('expo', 'module.exports = () => ({});');
-    const found = discoverPlugins([dep], readConfigFor({expo: true}));
+    declarePlugin(dep);
+    const found = discoverPlugins([dep], noConfig);
     expect(found).toHaveLength(1);
     expect(found[0].depName).toBe('expo');
     expect(typeof found[0].plugin).toBe('function');
   });
 
+  it('still discovers a plugin declared the deprecated way', () => {
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const dep = makeDep('expo', 'module.exports = () => ({});');
+      const found = discoverPlugins([dep], readConfigFor({expo: true}));
+      expect(found).toHaveLength(1);
+      expect(warnSpy).toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
   it('skips deps that do not declare a plugin', () => {
     const dep = makeDep('react-native-svg', null);
     expect(discoverPlugins([dep], readConfigFor({}))).toHaveLength(0);
   });
 
   it('honors the app deny-list (opt-out, no allowlist needed)', () => {
     const dep = makeDep('expo', 'module.exports = () => ({});');
-    const found = discoverPlugins([dep], readConfigFor({expo: true}), ['expo']);
-    expect(found).toHaveLength(0);
+    declarePlugin(dep);
+    expect(discoverPlugins([dep], noConfig, ['expo'])).toHaveLength(0);
   });
 
   it('accepts default/plugin export interop', () => {
     const a = makeDep('a', 'module.exports.default = () => ({});');
     const b = makeDep('b', 'module.exports.plugin = () => ({});');
-    const found = discoverPlugins([a, b], readConfigFor({a: true, b: true}));
+    declarePlugin(a);
+    declarePlugin(b);
+    const found = discoverPlugins([a, b], noConfig);
     expect(found.map(f => f.depName).sort()).toEqual(['a', 'b']);
   });
 
   it('fails closed when the plugin module is missing', () => {
     const dep = makeDep('expo', null); // opted in below but no plugin.js
-    expect(() => discoverPlugins([dep], readConfigFor({expo: true}))).toThrow(
+    declarePlugin(dep);
+    expect(() => discoverPlugins([dep], noConfig)).toThrow(
       /failed to load the autolinking plugin for 'expo'/,
     );
   });
 
   it('fails closed when the module does not export a function', () => {
     const dep = makeDep('expo', 'module.exports = {nope: 1};');
-    expect(() => discoverPlugins([dep], readConfigFor({expo: true}))).toThrow(
+    declarePlugin(dep);
+    expect(() => discoverPlugins([dep], noConfig)).toThrow(
       /does not export a function/,
     );
   });