skilld
All skills
callstackincubator avatar

/react-native-brownfield-migration

@fa0bad0 official
by Callstack Incubatorcallstackincubator/agent-skills1.7k stars
118

Implements an accepted incremental brownfield migration from native iOS or Android to React Native or Expo using @callstack/react-native-brownfield. Use after the brownfield path has been selected, when setting up the integration, packaging XCFramework or AAR artifacts, or adding React Native surfaces to native hosts.

Ask your Agent

Use this Skill: https://skilld.dev/gh/callstackincubator/agent-skills/react-native-brownfield-migration

This session only. Nothing lands on disk.

referencesbare-ios-native-integration.md

≈835 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Skill: Bare iOS Native Integration

Integrate bare RN XCFramework artifacts into native iOS host app and verify startup/runtime behavior.

Quick Command

ReactNativeBrownfield.shared.bundle = ReactNativeBundle
ReactNativeBrownfield.shared.startReactNative { print("React Native bundle loaded") }

When to Use

  • Consuming generated bare RN XCFrameworks in host iOS app
  • Wiring runtime initialization for UIKit or SwiftUI entrypoints

Prerequisites

Agent-Assisted Verification

Use agent-device after the host build succeeds. Read the agent-device skill or CLI help when available before exact commands. If it is missing and verification needs it, install it through the environment's approved/trusted path or ask the user to install or enable it. Then open the host app, navigate to the RN surface, capture snapshots/screenshots, and collect logs for Debug and Release behavior.

Step-by-Step Instructions

Progress checklist:
- [ ] Link generated frameworks
- [ ] Initialize RN startup
- [ ] Render registered module
- [ ] Verify Debug and Release behavior
  1. Link these frameworks into host app:
    • <framework_target_name>.xcframework
    • ReactBrownfield.xcframework
    • hermesvm.xcframework (or hermes.xcframework for older RN)
  2. In app startup:
import <framework_target_name>

ReactNativeBrownfield.shared.bundle = ReactNativeBundle
ReactNativeBrownfield.shared.startReactNative(onBundleLoaded: {
    print("React Native bundle loaded")
}, launchOptions: launchOptions)
  1. Render RN UI with JS-registered module name:
    • UIKit: ReactNativeViewController(moduleName: "<registered_module_name>")
    • SwiftUI: ReactNativeView(moduleName: "<registered_module_name>")
  2. Validate:
    • Debug with Metro (npx react-native start)
    • Release without Metro
    • Agent-assisted device evidence, using agent-device when possible

Stop Conditions

Mark complete only if:

  • host app builds in Debug and Release
  • RN module renders in both configurations

If Failed

  • Re-check startup order: set bundle -> start runtime -> create RN view/controller
  • Re-check moduleName matches AppRegistry.registerComponent
  • Re-link all required frameworks if Release cannot load JS

Canonical Docs

Common Pitfalls

  • Missing ReactNativeBrownfield.shared.bundle = ReactNativeBundle
  • Wrong module name compared to JS registration
  • Linking only app XCFramework without brownfield/hermes frameworks

Related Skills

Source: SKILL.md on GitHub

Third-party checks

No alerts17d5 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    The skill provides a workflow for migrating native mobile applications to React Native using the @callstack/react-native-brownfield library. It uses standard development tools, package managers, and vendor-provided CLI tools. No malicious patterns, obfuscation, or unauthorized data exfiltration were detected.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer7mo

    8/12 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at fa0bad0. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 weeks ago.

Activeupdated 2 months ago

Topics

  • react-native
  • brownfield
  • expo
  • ios
  • android
  • xcframework
  • aar
  • native-integration
  • migration

README badge

README badge for callstackincubator/agent-skills/react-native-brownfield-migration

What it does

Guides incremental adoption of React Native or Expo in existing native iOS and Android apps using @callstack/react-native-brownfield, covering initial setup, artifact packaging (XCFramework and AAR), and phased host app integration. Targets brownfield migration workflows where React Native surfaces are introduced into established native codebases.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with both Expo and bare React Native?
Yes. The skill provides separate tracks for Expo and bare React Native migration. You select one path based on your project state and do not mix steps between them.
What platforms does this skill target?
iOS and Android. For iOS it handles XCFramework generation and integration; for Android it handles AAR generation, publishing, and integration.
Can I use this skill to migrate an existing native app incrementally?
Yes. The skill prescribes a phased approach: assess your app, set up React Native via @callstack/react-native-brownfield, package artifacts, integrate one RN surface into the host app, then repeat by feature for incremental rollout.
Do I need to create a new React Native app first?
Only if you don't have one yet. If you're adding React Native to an existing native app, the skill assumes your host app is already present. If starting from scratch, the skill includes a path to scaffold a new Expo app before brownfield setup.
What happens if I'm unsure whether to use Expo or bare React Native?
The skill includes a path-selection gate that runs first. If your project state is ambiguous, the skill asks one disambiguating question before proceeding with exactly one track.

Generated from the current SKILL.md. These answers refresh after source changes.