React Native Brownfield Migration

title: Brownfield CLI and Configuration impact: CRITICAL tags: react-native, brownfield, cli, configuration, packaging

Skill: Brownfield CLI and Configuration

The command and configuration contract for the brownfield CLI. Read this before composing any packaging or publish command, and before adding flags to a package.json script.

Discover options before trusting this file

Flags move between versions. Run npx brownfield <command> --help for the command you are about to use and reconcile it with the tables below. Where they disagree, the help output wins — update this file rather than working around it.

Commands

--verbose is a global option available on every command.

The binary ships inside @callstack/brownfield-cli, which is a dependency of @callstack/react-native-brownfield — installing the brownfield package is enough to get npx brownfield.

package:ios

Both boolean-valued flags accept true/1/false/0; anything else fails with Invalid value for <flag>: expected true or false.

--archive and --local are inherited from the underlying build tooling, so they are accepted but unsupported. Do not plan a migration step around them — archive the host app in Xcode against the packaged frameworks instead.

package:android / publish:android

codegen and navigation:codegen

You rarely run these by hand — see Side effects.

Configuration file

Put stable per-project settings in a config file and keep only per-run flags on the command line. A project driven this way runs a bare npx brownfield package:ios.

Exactly one source is allowed. Two or more raises Project has multiple Brownfield configuration files:

1. brownfield.config.js (project root)

2. brownfield.config.json (project root)

3. the brownfield key in package.json

Shape

{
  "$schema": "https://oss.callstack.com/react-native-brownfield/schema.json",
  "verbose": true,
  "ios": {
    "scheme": "BrownfieldLib",
    "configuration": "Release",
    "expo": {}
  },
  "android": {
    "moduleName": "brownfieldlib",
    "variant": "release",
    "expo": { "useLocalMaven": true }
  },
  "brownie": {
    "kotlin": "./android/brownfieldlib/src/main/java/<package_path>/Generated/",
    "kotlinPackageName": "<kotlin_package_name>"
  }
}

• ios accepts the package:ios options; android accepts the package:android and publish:android options. Use the camelCase form of each flag (--use-prebuilt-expo -> usePrebuiltExpo, --add-spm-package -> addSpmPackage, --module-name -> moduleName).

• ios.expo and android.expo are Expo config plugin options for the prebuild scaffolding (framework name, bundle identifier, deployment target, Android package name, SDK versions, Maven coordinates, Proguard rules, missing dimension strategies). They are a different layer from the packaging flags above — consult the Expo integration docs for the current key list.

• brownie configures Brownie codegen output. A top-level brownie key in package.json is the legacy location and warns; prefer the nested key shown here.

• The config is validated against the published JSON schema. Validation problems are warnings, not errors — a typo'd key is silently ignored, so read the warnings.

Precedence

CLI options override config values for the same key, and the CLI logs a warning naming each overridden key and both values. Treat those warnings as a signal that a command line and a config file disagree about the project, and fix one of them.

Working shapes to copy

Each of the three sources has a working example in the react-native-brownfield repo's apps — see Reference apps.

Outputs

iOS artifacts land in <ios_source_dir>/.brownfield/package/build, and the intermediate build directory is <ios_source_dir>/.brownfield/build. For a bare app that is ios/.brownfield/...; for an Expo app the same paths apply under the prebuilt ios/ directory.

What appears there:

• <framework_target_name>.xcframework

• ReactBrownfield.xcframework (binary stripped — it is interface-only, to avoid duplicate symbols)

• hermesvm.xcframework (named hermes.xcframework on older React Native; hosts that expect one name may need the other renamed)

• Brownie.xcframework, when the project uses Brownie

• BrownfieldNavigation.xcframework, when the project uses Brownfield Navigation

• React Native and Expo support XCFrameworks emitted alongside, when prebuilts are in use

With --add-spm-package, the XCFrameworks are moved into a spm-artifacts/ subdirectory and Package.swift is written next to them. See expo-ios-integration.md for wiring the package into the host project — the CLI does not do that part.

Android artifacts are published to Maven local by publish:android under the group, artifact and version configured in the library module's publishing block.

Side effects: codegen runs automatically

package:ios, package:android and publish:android each run Brownie codegen and Brownfield Navigation codegen first, when the project uses those packages. Consequences:

• A change to a Brownie store definition or a navigation spec is picked up by the next package run. You do not need a separate codegen step before packaging.

• Generated native sources are refreshed under node_modules and, for Kotlin, at the configured brownie.kotlin output path. Do not hand-edit generated files; change the spec and re-package.

• A codegen failure fails the package command before any build work happens — read the first error, not the last.

For the store and navigation contracts themselves, use the dedicated brownie and brownfield-navigation skills if they are installed. They are distributed separately from this skill, so invoke them by name rather than by path.

Canonical Docs

• Brownfield CLI

• Configuration

• Expo Integration

Common Pitfalls

• Repeating the same flags on every command instead of writing them once to brownfield.config.*

• Two config sources present at once (the CLI refuses to run)

• Assuming a flag exists because it appears in an older reference, instead of running --help

• Planning around --archive / --local on package:ios

• Treating the config schema warning as harmless when a key was simply misspelled

• Looking for artifacts under .brownfield/package instead of .brownfield/package/build

Related Skills

• runtime-api.md - Host <-> RN API surface

• expo-ios-integration.md - Expo iOS packaging and host wiring

• bare-ios-xcframework-generation.md - Bare iOS packaging