Brownie

Overview

Brownie provides cross-platform shared state for React Native brownfield apps. The workflow starts from *.brownie.ts store definitions, runs brownfield codegen (or packaging commands that include codegen), then uses typed APIs on TypeScript, Android, and iOS sides.

When to Apply

Reference this skill when:

• Setting up @callstack/brownie in an existing brownfield app
• Defining or changing store schemas in *.brownie.ts
• Using useStore, subscribe, getSnapshot, or setState on the JS side
• Registering and consuming stores in Android or iOS hosts
• Packaging and embedding iOS frameworks that include Brownie

Quick Reference

• Install Brownie:

npm install @callstack/brownie

• Generate native types:

npx brownfield codegen

• Packaging commands also include Brownie codegen:

# iOS
npx brownfield package:ios --scheme YourScheme --configuration Release

# Android
npx brownfield package:android --module-name :YourModuleName --variant release
npx brownfield publish:android --module-name :YourModuleName

Routing (concern -> file)

Retrieval and Response Rules

• Single-reference-first: choose exactly one primary reference from the table above that best matches the request before opening any other file.
• Stop-after-sufficiency: once the required command/API is found for the request, stop reading additional references.
• Cross-reference only when blocked: open a second reference only if the first one does not contain the needed command/API.
• Testing-context response budget:
• Return compact actionable steps only.
• Use at most one code snippet.
• Do not restate overview/scope/background sections.

Brownie Android Usage

Minimum prerequisites

• package.json has brownie.kotlin and brownie.kotlinPackageName.
• Gson is available in native dependencies: com.google.code.gson:gson.
• Generated Kotlin store types already exist.

Exact steps

1. Register the store once at startup with registerStoreIfNeeded. 2. Read/update the typed store using StoreManager.shared.store<T>(STORE_NAME). 3. Build/publish artifacts when needed:

• npx brownfield package:android --module-name :YourModuleName --variant release
• npx brownfield publish:android --module-name :YourModuleName

Verification command/API

• Required API: registerStoreIfNeeded(storeName) { initialState }
• Success signal: StoreManager.shared.store<T>(STORE_NAME) returns a non-null store and updates propagate.

One short example

import com.callstack.brownie.StoreManager
import com.callstack.brownie.registerStoreIfNeeded
import com.callstack.brownie.store
import com.rnapp.brownfieldlib.AppStore

registerStoreIfNeeded(storeName = AppStore.STORE_NAME) {
  AppStore(counter = 0.0)
}

val store = StoreManager.shared.store<AppStore>(AppStore.STORE_NAME)
store?.set { state -> state.copy(counter = state.counter + 1) }

Brownie Getting Started

Minimum prerequisites

• Brownfield setup already works in the project.
• @callstack/react-native-brownfield is installed.
• Native host app exists (iOS and/or Android).

Exact steps

1. Install Brownie:

• npm install @callstack/brownie

2. Define a store in a *.brownie.ts file:

• create a store interface extending BrownieStore
• augment declare module '@callstack/brownie' { interface BrownieStores { ... } }

3. Import that *.brownie.ts file from app entry (App.tsx or index.js). 4. Generate native types:

• npx brownfield codegen

5. Use the store on JS side (useStore) and register the generated store in native startup.

Verification command/API

• Required command: npx brownfield codegen
• Success signal: generated native files are present and app builds with typed store usage.

One short example

import type { BrownieStore } from '@callstack/brownie';

interface UserStore extends BrownieStore {
  name: string;
}

declare module '@callstack/brownie' {
  interface BrownieStores {
    user: UserStore;
  }
}

Brownie Store Definition and Codegen

Use this for store schema authoring and regeneration issues.

Store contract

• File ends with .brownie.ts
• Store interface extends BrownieStore
• Module augmentation adds the store to BrownieStores
• Store key matches intended public name

Example

import type {BrownieStore} from '@callstack/brownie';

interface AppStore extends BrownieStore {
  counter: number;
  user: {name: string};
}

declare module '@callstack/brownie' {
  interface BrownieStores {
    AppStore: AppStore;
  }
}

Codegen workflow

1. Import each store file from app entry. 2. Run npx brownfield codegen. 3. Rebuild native artifacts after schema changes.

Common fixes

• Missing generated files: verify .brownie.ts suffix and augmentation.
• Stale native/JS types: rerun codegen and rebuild.

Brownie Swift Usage and XCFramework Packaging

Use this for iOS registration, Swift usage, and packaging.

Package and embed

1. Run npx brownfield package:ios --scheme YourScheme --configuration Release 2. Add generated frameworks to Xcode and set Embed & Sign 3. Ensure Brownie.xcframework, ReactBrownfield.xcframework, and Hermes framework are included

Startup registration

Call YourStore.register(initialState) before first read/subscription.

SwiftUI / UIKit usage

import Brownie
import SwiftUI

struct CounterView: View {
  @UseStore(\AppStore.counter) var counter

  var body: some View {
    Button("Increment") { $counter.set { $0 + 1 } }
  }
}

UIKit: resolve via StoreManager.get(key:as:), subscribe, and cancel on teardown.

Common fixes

• No such module 'Brownie': verify framework embed/sign.
• No UI updates: ensure store registered before use.

Brownie TypeScript Usage

Use this for React Native store reads/updates.

Hook pattern

Use useStore(storeKey, selector) and keep selectors narrow to reduce rerenders.

import {useStore} from '@callstack/brownie';

const [counter, setState] = useStore('AppStore', (s) => s.counter);
setState((prev) => ({counter: prev.counter + 1}));

Low-level APIs

• subscribe(storeKey, onChange)
• getSnapshot(storeKey)
• setState(storeKey, patchOrUpdater)

Common fixes

• TS key/type mismatch: ensure store definition file is imported in app entry.
• Drift after schema edits: rerun codegen/package and rebuild host apps.