@matiks/rn-app-state

Nitro-powered native app state module for React Native. Provides a reactive hook that tracks app lifecycle state (active, background, killed) using native code via JSI -- zero bridge overhead.

Features

• Reactive hook -- useNitroAppState() triggers re-renders on state changes
• Native lifecycle observation -- iOS (NotificationCenter) + Android (ProcessLifecycleOwner)
• Kill detection -- wasKilledLastSession flag detected on cold start via persisted clean-exit flag
• Notification support -- getStateOnNotification() returns the app state at the moment of a push/silent notification
• Web fallback -- Uses React Native's AppState API on web (no Nitro required)
• Thread-safe -- Both iOS and Android implementations handle concurrent access correctly

Installation

yarn add @matiks/rn-app-state
cd ios && pod install

Usage

import { useNitroAppState } from '@matiks/rn-app-state'

function MyComponent() {
  const { appState, wasKilledLastSession, getStateOnNotification } = useNitroAppState()

  useEffect(() => {
    if (appState === 'active') {
      // Refresh data, resume animations, etc.
    }
  }, [appState])

  return <Text>App State: {appState}</Text>
}

API

useNitroAppState()

Returns:

| Property | Type | Description | |---|---|---| | appState | 'active' \| 'background' \| 'killed' | Current app lifecycle state. Reactive. | | wasKilledLastSession | boolean | Whether the app was force-killed in the previous session. | | getStateOnNotification | () => AppStateType | Synchronous call to get native state at notification receipt time. |

States

• active -- App is in the foreground and interactive
• background -- App is in the background (iOS inactive is merged into background)
• killed -- Previous session was force-terminated (reported briefly on cold start, then transitions to active)

Requirements

• React Native 0.76+
• react-native-nitro-modules 0.33.x
• iOS 16.0+
• Android minSdk 23+

Development

# Generate nitrogen bridge code
yarn specs

# Type check
yarn typecheck