Adding one React Native screen to an existing Swift or Kotlin app

Sources checked on 5 November 2026.

An existing iOS or Android app can host a React Native screen without replacing its entire interface. The official React Native guide describes adding a view or user flow to a native app. This still requires integration with the iOS or Android project, rather than simply building a JavaScript component. Integration with Existing Apps — React Native.

The question before the first screen is therefore how it will work with the rest of the product. The team needs to establish who opens and closes it, where the user’s session comes from, and what happens to an operation when the app is interrupted. A single screen may have a small visual scope while touching many dependencies.

The second model is described in the Native Platform documentation. This article concerns the third, often called brownfield integration. Accessing a native capability from RN does not, by itself, establish that a native app is ready to host an RN screen.

A useful candidate for assessment has a clear entry point, an exit and a limited set of data. An order-status view or part of a loyalty programme could be examples. These are hypothetical scenarios, not client projects. If the screen also requires changes to authentication, payments and the entire navigation structure, those dependencies belong in the assessment. Each native app and its release also need an identified owner.

• A new React Native app. Starting point: A new product with an RN interface Decision to make: The architecture and dependencies of the whole product.
• A native module or component inside an RN app. Starting point: An RN app using platform code or a platform view Decision to make: How that capability is exposed to RN code.
• An RN screen inside a native app. Starting point: An existing Swift/Kotlin product opening an RN view Decision to make: How the screen works with the native host and the rest of the app.

The following list proposes design questions rather than a mandatory architecture. The host is the existing native app. Ownership and mechanisms must be chosen for the particular product.

Callstack documents a mechanism in which RN code calls the host’s navigation through a defined contract and native delegates. This is a specific integration pattern, rather than automatic synchronisation of every navigation stack. Before choosing it, describe the back gesture, links opening the screen from outside the app, and closing the view halfway through an operation. Brownfield Navigation — Callstack.

• Navigation. Establish on the host side: When the screen opens and which parameters it receives Establish on the RN screen side: How it reports completion or requests another destination Shared decision: Who changes the navigation stack; what Back and cancellation mean
• Lifecycle. Establish on the host side: Which events and restoration behaviour the app handles Establish on the RN screen side: What happens when activity is lost and regained Shared decision: How the view resumes without repeating an operation
• State. Establish on the host side: Which data is authoritative and who updates it Establish on the RN screen side: Which data is local UI state only Shared decision: The format, version and freshness of exchanged data
• Identity. Establish on the host side: Who owns the session, sign-out and session refresh Establish on the RN screen side: How the screen obtains the user context it needs Shared decision: How both parts respond to an expired session
• In-flight operations. Establish on the host side: Who can establish the business operation’s outcome Establish on the RN screen side: How the screen shows pending, failed and confirmed states Shared decision: How operations are identified and retries handled
• Analytics. Establish on the host side: Who emits app-wide events Establish on the RN screen side: Who emits events for the new view Shared decision: One event definition and a way to prevent duplicates

Authentication context involves more than passing a user identifier. The team should establish who refreshes authorisation, what sign-out means, and how the screen responds when the account changes. Tokens should not be moved into an arbitrary store just because JavaScript can access it. RN’s documentation distinguishes ordinary and sensitive storage; Async Storage is not a place for tokens. Security — React Native.

UI state also needs to be distinguished from business state. A list position or open tab is different from confirmation that an order has been accepted. Callstack describes Brownie, a library for sharing state between RN and native code. Choosing such a tool does not decide which data is authoritative or who resolves a conflict. Brownie — Callstack.

RN provides AppState to observe app activity. It supplies a signal for handling state changes, rather than a complete screen-restoration or order-completion mechanism. AppState — React Native.

On iOS, the interface scene’s lifecycle needs to be considered separately from the app process. On Android, a ViewModel can survive configuration changes but not system-initiated process death. The integration needs to account for the relevant platform model: returning to an app does not establish that all in-memory data still exists. UIKit scenes — Apple, saving view state — Android.

saving view state — Android.

At the review date, Callstack’s documentation provides tables of tested React Native, Expo and brownfield package combinations. These are not a promise of support for every older app. A project assessment should record the selected versions, the documentation date and the result of checking dependencies. Compatibility tables — Callstack.

The record should include the RN version and architecture, Expo if used, required native libraries, the iOS/Android toolchain, minimum operating systems and how RN code reaches the app release. Responsibility for updates after the first integration also needs to be settled. Instructions from a different documentation version should not be treated as evidence that the whole product is compatible.

Suppose the native app already has authentication and an order list, while a new RN screen displays the details of a selected order. This is an example for a design discussion, rather than a GMI case study or a complete specification.

The host opens the screen with the agreed context. The team defines data access, permissions and behaviour after an account change. The screen reports closure through the agreed contract. If it also allows an operation, such as cancelling an order, the team must establish how to check the outcome when a response is lost. A missing response in the interface must not, by itself, be interpreted as either success or definite failure.

This is not a comparison of rebuilding an entire app with repairing it. It is an assessment of a particular boundary between an existing native product and a new screen.

The scenarios below propose acceptance criteria for this example. Expected outcomes must be agreed with the relevant system owners; this is not a report of tests already performed.

Android documents Back at the task and Activity-stack level, with configuration-dependent exceptions. The behaviour of the actual host therefore needs checking; a rule for one stack should not be transferred automatically to another. Tasks and the back stack — Android.

• Enter from the native order list and return. Expected outcome to agree: The correct order is shown; return reaches the agreed location without an extra screen or loss of necessary context.
• Use Back, a back gesture or the close button. Expected outcome to agree: The agreed navigation owner handles the action consistently. The Android Activity stack and RN’s internal stack are not treated as the same mechanism.
• The session expires during entry or following external authentication. Expected outcome to agree: There is a defined route to re-authentication or exit; data from the previous account is not shown.
• The app moves to the background, resumes or is restored after process death. Expected outcome to agree: UI state and business data are re-established under the contract, without assuming memory continuity.
• An operation is sent but its response does not arrive. Expected outcome to agree: The user sees the agreed pending or uncertain state. Retrying does not create a second operation, using an agreed mechanism in the responsible system.
• The host and RN observe the same purchase. Expected outcome to agree: The business event is counted once under a shared definition; redisplaying the view is not counted as another purchase.
• RN code fails to start or data cannot be read. Expected outcome to agree: There is an agreed error and exit path, without displaying a false confirmation.
• The new screen is disabled. Expected outcome to agree: The alternative route and the handling of operations started before disablement are known.

Disabling an entry point, returning to a previous view and rolling back an entire app release are different actions. The team must establish which are actually available, who can initiate them, and how long old and new data contracts need to coexist. This example does not assume that a feature flag or remote-disable mechanism exists.

Restoring the UI does not reverse an order or another business operation that has already been accepted. Apple’s state-restoration documentation concerns reconstructing the interface and requires the app to provide restoration data and handling. It is not a transaction-reversal mechanism. Restoring your app’s state — Apple.

Before deciding on a first screen, collect the app and dependency versions, navigation diagram, session rules, operation descriptions, release owners and expected error behaviour. These provide a basis for discussing feasibility and confirming the assessment scope. A library description alone does not determine cost, timing or suitability for a particular app.