Brownfield Navigation

Overview

Brownfield navigation has three steps: 1. Define brownfield.navigation.ts 2. Run npx brownfield navigation:codegen 3. Wire native delegates before JS calls

Read only the smallest reference that matches the question.

Routing (concern -> file)

Minimal command reference

npx brownfield navigation:codegen
npx brownfield package:ios
npx brownfield package:android
npx brownfield publish:android

JavaScript Usage

Use this file for React Native call sites and JS-facing failures.

Call pattern

import BrownfieldNavigation from '@callstack/brownfield-navigation';

BrownfieldNavigation.openNativeProfile('user-123');

Checklist

• Call generated methods directly from user actions first
• Keep params explicit and stable
• Keep method names aligned with generated API

Fast triage

• undefined is not a function:
• Usually codegen/rebuild drift after contract edits
• Method exists but opens wrong screen:
• Usually delegate wiring issue (see native docs)
• Crash on first call:
• Often delegate registration order issue (see native docs)

Recovery order

1. Confirm contract shape 2. Run npx brownfield navigation:codegen 3. Rebuild iOS/Android 4. Retest JS call

Native Integration (Android)

Implement delegate

• Implement generated BrownfieldNavigationDelegate
• Route each generated method to intended native destination
• Map params directly (for example through Intent extras)

Register delegate at startup

• Call:
• BrownfieldNavigationManager.setDelegate(...)
• Register in startup flow (for example onCreate)
• Ensure registration happens before RN calls

Minimal pattern

class MainActivity : AppCompatActivity(), BrownfieldNavigationDelegate {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    BrownfieldNavigationManager.setDelegate(this)
  }

  override fun openNativeProfile(userId: String) {
    val intent = Intent(this, ProfileActivity::class.java).apply {
      putExtra("userId", userId)
    }
    startActivity(intent)
  }
}

Native Integration (iOS)

Implement delegate

• Conform to generated BrownfieldNavigationDelegate
• Route each generated method to intended UIKit/SwiftUI destination
• Execute presentation on main thread

Register delegate at startup

• Call:
• BrownfieldNavigationManager.shared.setDelegate(navigationDelegate: ...)
• Register before RN screens that call Brownfield navigation are shown
• Keep a strong delegate reference for app lifetime

Minimal pattern

final class AppNavigationDelegate: BrownfieldNavigationDelegate {
  func openNativeProfile(userId: String) {
    DispatchQueue.main.async {
      // present native screen
    }
  }
}

BrownfieldNavigationManager.shared.setDelegate(navigationDelegate: navigationDelegate)

Setup and Codegen

Use this file for contract shape and generation behavior.

Contract requirements

• File name: brownfield.navigation.ts
• File location: React Native app root
• Interface name: BrownfieldNavigationSpec or Spec
• Prefer void navigation methods
• Promise-returning methods are not supported by generated native implementations

Codegen

• Default command: npx brownfield navigation:codegen
• Explicit path: npx brownfield navigation:codegen <specPath>
• Use explicit path when running outside app root or in monorepos

Artifact location

Generated files are written under resolved @callstack/brownfield-navigation package root.

Typical outputs:

• src/NativeBrownfieldNavigation.ts
• src/index.ts
• ios/BrownfieldNavigationDelegate.swift
• ios/NativeBrownfieldNavigation.mm
• android/src/main/java/<generated-package>/BrownfieldNavigationDelegate.kt
• android/src/main/java/<generated-package>/NativeBrownfieldNavigationModule.kt

Regeneration rule

If contract surface changes (method names, params, types, optionality): 1. Update brownfield.navigation.ts 2. Run codegen 3. Rebuild native apps