SPM: allow overriding the autolinking config command

The SwiftPM autolinking flow hardcodes `@react-native-community/cli config`
to generate autolinking.json. Apps that replace community autolinking — most
notably Expo, which ships expo-modules-autolinking instead of @rncli — have no
injection point, so the command fails, autolinking.json is never written, and
the Autolinked SwiftPM package is emitted empty (external native modules can't
be imported).

CocoaPods already solves this: `use_native_modules!(config_command)` takes the
command as a parameter, letting an Expo Podfile pass its own. This adds the
equivalent hook to the SPM path:

  - `--config-command '<json argv array>'` CLI flag, and
  - the `RCT_SPM_AUTOLINKING_CONFIG_COMMAND` env var (same JSON-array format),
    which the injected Xcode build phase can read even when it can't rewrite argv.

Both go through one validator; precedence is flag > env > default. The value is
the command to run (its stdout is captured as the config JSON), mirroring
CocoaPods — not a precomputed result.

## Changelog:
[IOS] [ADDED] - Allow overriding the SwiftPM autolinking config command via --config-command / RCT_SPM_AUTOLINKING_CONFIG_COMMAND

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: chrfalch

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

@@ -55,6 +55,7 @@
  *                               must contain debug/ and release/ cache slots.
  *   [advanced] --download <auto|skip|force> Artifact policy (default: auto).
  *   [advanced] --skip-codegen   Skip the react-native codegen step.
+ *   [advanced] --config-command <json> Override the autolinking config command.
  *
  * Steps performed (add/update):
  *   1. react-native codegen → build/generated/ios/ + install SPM codegen template
@@ -83,6 +84,7 @@ const {
 } = require('./spm/generate-spm-autolinking');
 const {
   generateAutolinkingConfig,
+  parseConfigCommandJson,
 } = require('./spm/generate-spm-autolinking-config');
 const {main: generatePackage} = require('./spm/generate-spm-package');
 const {findSourcePath} = require('./spm/generate-spm-package');
@@ -187,6 +189,11 @@ function parseArgs(argv /*: Array<string> */) /*: SetupArgs */ {
       default: false,
       describe: '[advanced] Skip the react-native codegen step',
     })
+    .option('config-command', {
+      type: 'string',
+      describe:
+        '[advanced] JSON array of the argv used to generate autolinking.json, overriding the default @react-native-community/cli config command. Also settable via RCT_SPM_AUTOLINKING_CONFIG_COMMAND. Example: \'["npx","expo-modules-autolinking","react-native-config","--json","--platform","ios"]\'',
+    })
     .usage(
       'Usage: $0 [action] [options]\n\nSets up Swift Package Manager support in a React Native app.',
     )
@@ -214,6 +221,10 @@ function parseArgs(argv /*: Array<string> */) /*: SetupArgs */ {
     version: parsed.version ?? null,
     artifacts: parsed.artifacts ?? null,
     skipCodegen: parsed['skip-codegen'],
+    configCommand:
+      parsed['config-command'] != null
+        ? parseConfigCommandJson(parsed['config-command'], '--config-command')
+        : null,
     downloadPolicy: parsed.download,
     productName: parsed['product-name'] ?? null,
     xcodeprojPath: parsed.xcodeproj ?? null,
@@ -982,7 +993,10 @@ async function main(argv /*:: ?: Array<string> */) /*: Promise<void> */ {
   if (needsCliConfig) {
     log('Generating autolinking.json (CLI config)...');
     try {
-      autolinkingConfigResult = generateAutolinkingConfig({projectRoot});
+      autolinkingConfigResult = generateAutolinkingConfig({
+        projectRoot,
+        configCommand: args.configCommand ?? undefined,
+      });
       log(
         `Wrote ${path.relative(appRoot, autolinkingConfigResult.outputPath)}`,
       );
@@ -1159,6 +1173,7 @@ module.exports = {
   main,
   detectStandardRnLayoutRedirect,
   findInjectedXcodeproj,
+  parseArgs,
   resolveAction,
   shouldAutoDeintegrate,
   ensureBothArtifactFlavors,

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

@@ -36,6 +36,20 @@ const os = require('node:os');
 const path = require('node:path');
 
 let tmpProjects = [];
+let originalConfigCommandEnv;
+
+beforeEach(() => {
+  originalConfigCommandEnv = process.env.RCT_SPM_AUTOLINKING_CONFIG_COMMAND;
+  delete process.env.RCT_SPM_AUTOLINKING_CONFIG_COMMAND;
+});
+
+afterEach(() => {
+  if (originalConfigCommandEnv == null) {
+    delete process.env.RCT_SPM_AUTOLINKING_CONFIG_COMMAND;
+  } else {
+    process.env.RCT_SPM_AUTOLINKING_CONFIG_COMMAND = originalConfigCommandEnv;
+  }
+});
 
 function makeTmpProject() {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'spm-autolink-config-'));
@@ -256,4 +270,95 @@ describe('generateAutolinkingConfig', () => {
       rawJson: raw,
     });
   });
+
+  describe('config command override', () => {
+    it('uses the config command from RCT_SPM_AUTOLINKING_CONFIG_COMMAND', () => {
+      const {projectRoot, iosDir} = makeTmpProject();
+      const raw = JSON.stringify(fakeCliConfig(iosDir));
+      let receivedCommand = null;
+      process.env.RCT_SPM_AUTOLINKING_CONFIG_COMMAND = JSON.stringify([
+        'my-cli',
+        'config',
+      ]);
+
+      generateAutolinkingConfig({
+        projectRoot,
+        cliRunner: command => {
+          receivedCommand = command;
+          return {stdout: raw, stderr: '', exitCode: 0};
+        },
+      });
+
+      expect(receivedCommand).toEqual(['my-cli', 'config']);
+    });
+
+    it('prefers an explicit configCommand over the environment variable', () => {
+      const {projectRoot, iosDir} = makeTmpProject();
+      const raw = JSON.stringify(fakeCliConfig(iosDir));
+      let receivedCommand = null;
+      process.env.RCT_SPM_AUTOLINKING_CONFIG_COMMAND = JSON.stringify([
+        'environment',
+        'config',
+      ]);
+
+      generateAutolinkingConfig({
+        projectRoot,
+        configCommand: ['explicit', 'config'],
+        cliRunner: command => {
+          receivedCommand = command;
+          return {stdout: raw, stderr: '', exitCode: 0};
+        },
+      });
+
+      expect(receivedCommand).toEqual(['explicit', 'config']);
+    });
+
+    it('throws when the environment variable is not JSON', () => {
+      const {projectRoot} = makeTmpProject();
+      process.env.RCT_SPM_AUTOLINKING_CONFIG_COMMAND = 'not json';
+
+      expect(() =>
+        generateAutolinkingConfig({
+          projectRoot,
+          cliRunner: () => ({stdout: '{}', stderr: '', exitCode: 0}),
+        }),
+      ).toThrow(/RCT_SPM_AUTOLINKING_CONFIG_COMMAND/);
+    });
+
+    it.each(['[]', '[1,2]'])(
+      'throws when the environment variable is not a non-empty string array: %s',
+      rawConfigCommand => {
+        const {projectRoot} = makeTmpProject();
+        process.env.RCT_SPM_AUTOLINKING_CONFIG_COMMAND = rawConfigCommand;
+
+        expect(() =>
+          generateAutolinkingConfig({
+            projectRoot,
+            cliRunner: () => ({stdout: '{}', stderr: '', exitCode: 0}),
+          }),
+        ).toThrow(/RCT_SPM_AUTOLINKING_CONFIG_COMMAND/);
+      },
+    );
+
+    it('falls back to the default command when the environment variable is unset', () => {
+      const {projectRoot, iosDir} = makeTmpProject();
+      const raw = JSON.stringify(fakeCliConfig(iosDir));
+      let receivedCommand = null;
+
+      generateAutolinkingConfig({
+        projectRoot,
+        cliRunner: command => {
+          receivedCommand = command;
+          return {stdout: raw, stderr: '', exitCode: 0};
+        },
+      });
+
+      expect(receivedCommand).toEqual([
+        'npx',
+        '--no-install',
+        '@react-native-community/cli',
+        'config',
+      ]);
+    });
+  });
 });

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

@@ -14,6 +14,7 @@ const {
   detectStandardRnLayoutRedirect,
   ensureBothArtifactFlavors,
   findInjectedXcodeproj,
+  parseArgs,
   resolveAction,
   shouldAutoDeintegrate,
 } = require('../../setup-apple-spm');
@@ -59,6 +60,29 @@ function gitInitAndCommit(dir) {
   execFileSync('git', ['commit', '-m', 'init'], opts);
 }
 
+describe('parseArgs', () => {
+  it('parses --config-command as a JSON argv array', () => {
+    const args = parseArgs([
+      'update',
+      '--config-command',
+      '["a","b","config"]',
+    ]);
+
+    expect(args.action).toBe('update');
+    expect(args.configCommand).toEqual(['a', 'b', 'config']);
+  });
+
+  it('sets configCommand to null when --config-command is omitted', () => {
+    expect(parseArgs(['update']).configCommand).toBeNull();
+  });
+
+  it('throws for an invalid --config-command value', () => {
+    expect(() => parseArgs(['update', '--config-command', 'not json'])).toThrow(
+      /--config-command/,
+    );
+  });
+});
+
 // ---------------------------------------------------------------------------
 // resolveAction — zero-arg default. Explicit action wins; otherwise `update`
 // when an injection marker exists, else `add` (first run).

packages/react-native/scripts/spm/generate-spm-autolinking-config.js

@@ -16,6 +16,8 @@
  *
  * Invokes the React Native community CLI to produce its config and writes the
  * raw JSON to <project.ios.sourceDir>/build/generated/autolinking/autolinking.json.
+ * The config command can be overridden by `--config-command` or
+ * `RCT_SPM_AUTOLINKING_CONFIG_COMMAND`, in that order, before the default.
  *
  * No filtering or reshaping happens here — the downstream consumer
  * (generate-spm-autolinking.js) does its own iOS-only filtering when reading
@@ -60,6 +62,32 @@ const FALLBACK_CONFIG_COMMAND = [
   'config',
 ];
 
+function parseConfigCommandJson(
+  raw /*: string */,
+  source /*: string */,
+) /*: Array<string> */ {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      `${source}: config command must be a JSON array of strings. Example: '["npx","@react-native-community/cli","config"]'`,
+    );
+  }
+
+  if (
+    !Array.isArray(parsed) ||
+    parsed.length === 0 ||
+    !parsed.every(value => typeof value === 'string' && value.length > 0)
+  ) {
+    throw new Error(
+      `${source}: config command must be a non-empty JSON array of non-empty strings`,
+    );
+  }
+
+  return parsed;
+}
+
 function resolveDefaultConfigCommand(
   projectRoot /*: string */,
 ) /*: Array<string> */ {
@@ -94,6 +122,19 @@ function resolveDefaultConfigCommand(
   return FALLBACK_CONFIG_COMMAND;
 }
 
+// Env-var / default resolution for the autolinking config command. An explicit
+// `configCommand` (e.g. from `--config-command`) is handled upstream by
+// generateAutolinkingConfig's destructuring default, so it never reaches here —
+// this only decides between the env-var override and the built-in default.
+function resolveConfigCommand(projectRoot /*: string */) /*: Array<string> */ {
+  const raw = process.env.RCT_SPM_AUTOLINKING_CONFIG_COMMAND;
+  if (typeof raw === 'string' && raw.trim().length > 0) {
+    return parseConfigCommandJson(raw, 'RCT_SPM_AUTOLINKING_CONFIG_COMMAND');
+  }
+
+  return resolveDefaultConfigCommand(projectRoot);
+}
+
 function defaultCliRunner(
   command /*: Array<string> */,
   opts /*: {cwd: string} */,
@@ -116,7 +157,7 @@ function generateAutolinkingConfig(
 ) /*: GenerateAutolinkingConfigResult */ {
   const {
     projectRoot,
-    configCommand = resolveDefaultConfigCommand(projectRoot),
+    configCommand = resolveConfigCommand(projectRoot),
     cliRunner = defaultCliRunner,
   } = opts;
 
@@ -158,4 +199,9 @@ function generateAutolinkingConfig(
   return {config, outputPath: outPath, rawJson};
 }
 
-module.exports = {generateAutolinkingConfig, resolveDefaultConfigCommand};
+module.exports = {
+  generateAutolinkingConfig,
+  parseConfigCommandJson,
+  resolveConfigCommand,
+  resolveDefaultConfigCommand,
+};

packages/react-native/scripts/spm/spm-types.js

@@ -16,6 +16,9 @@ export type SetupArgs = {
   // `debug/` and `release/` cache slots, each with artifacts.json.
   artifacts: string | null,
   skipCodegen: boolean,
+  // Overrides the autolinking config command; also settable via
+  // RCT_SPM_AUTOLINKING_CONFIG_COMMAND.
+  configCommand: Array<string> | null,
   // Artifact download policy: 'auto' fetches when missing, 'skip' never
   // fetches, 'force' clears the cache slot and re-downloads.
   downloadPolicy: 'auto' | 'skip' | 'force',