How kingstinct/react-native-device-activity works
Project type and purpose
• This is a monorepo containing:
– A React Native “example” app (under apps/example) for demonstration and manual testing.
– An open-source React Native module (packages/react-native-device-activity) that exposes Apple’s Screen Time, Device Activity, and Shield APIs to JS.
– An Expo Config Plugin (in packages/.../config-plugin) that injects native iOS targets into the host app at build/prebuild time.
• Purpose: Provide a JS/TS interface plus an Expo plugin to configure and bundle iOS app extensions that implement family-control features on iOS 15+.
File structure
• Top-level monorepo with:
– apps/ (the example consumer app, containing React Native UI, Android and iOS projects, Swift UI views, native extensions under ios/targets).
– packages/react-native-device-activity/ (the library):
• src/ – JS/TS wrappers and types for the NativeModule bridge.
• ios/ – Swift implementation of the NativeModule plus view factories.
• config-plugin/ – Node scripts that hook into Expo prebuild to copy & configure three iOS app extensions: ActivityMonitorExtension, ShieldAction, ShieldConfiguration.
• expo-module.config.json – declares the module to the Expo plugin system.
– scripts/ – workspace maintenance.
• Build orchestration files (.github/workflows, husky, metro.config.js, tsconfig.json, babel.config.js, etc.)
README for architectural clues
• Describes:
– JS API for requesting authorization, starting/stopping monitors, listening to events, blocking selections, updating shield UI.
– Under-the-hood: uses UserDefaults for persisting configurations and history; runs background processes in iOS app extensions to respond to OS events; requires custom Dev Client.
Main components
A. Example App (apps/example):
– React Native UI (TypeScript, React components, SwiftUI wrappers).
– JS code invoking ReactNativeDeviceActivity.* APIs.
B. JS Bridge Layer (packages/.../src):
– Exposed methods: requestAuthorization, startMonitoring, blockSelection, updateShield, DeviceActivitySelectionView, event listeners.
– Internally calls React Native’s NativeModules to route calls to Swift.
C. Expo Config Plugin (packages/.../config-plugin):
– Build/prebuild plugin hooks.
– Reads expo config (appleTeamId, appGroup), invokes withCopyTargetFolder, withEntitlements, withInfoPlist, withXcodeSettings.
– Outputs three iOS extensions into the host app’s targets folder.
D. iOS Native Module (packages/.../ios):
– Swift implementation of ReactNativeDeviceActivityModule.
– Implements methods that call Apple’s DeviceActivityMonitor, Shielding APIs, persists to UserDefaults.
– Exposes DeviceActivitySelectionView using SwiftUI bridged into React Native.
E. iOS App Extension Targets (both in packages and copied into apps/example/targets):
– ActivityMonitorExtension – background monitor handling.
– ShieldAction – shield UI renderer and action handler.
– ShieldConfiguration – provides configuration/PrivacyInfo for Shield UI.
– These run in separate processes invoked by iOS when an event fires.
F. Apple’s Screen Time / Device Activity / Family Controls OS APIs:
– The system services that the Swift code calls into.
G. Data persistence:
– UserDefaults store for familyActivitySelectionId mappings, triggers, event history, shieldIds.
Relationships & interactions
• Build Time (prebuild/expo prebuild):
1. User runs expo prebuild / eas build.
2. Expo config plugin activates:
– Reads app.json, copies Swift target folders from node_modules into apps/xxx/targets.
– Modifies Info.plist, entitlements, Xcode project settings.
• Runtime (app launch & usage):
1. JS UI calls ReactNativeDeviceActivity.requestAuthorization() → JS Bridge → Swift NativeModule.
2. Swift module calls ScreenTime API → OS permission dialog → callback → JS.
3. JS invokes startMonitoring → Swift schedules monitors in ActivityMonitorExtension.
4. OS triggers ActivityMonitorExtension when time interval starts/ends or threshold reached → Swift extension writes to UserDefaults, may trigger ShieldAction or send events.
5. If Shield UI is needed, OS launches ShieldActionExtension → renders custom UI.
6. JS can listen to events via onDeviceActivityMonitorEvent (active app) or query history using getEvents().
Architectural patterns and design principles
• Monorepo with clear separation: example app vs library package.
• React Native NativeModule bridging pattern.
• Expo Config Plugin pattern for build-time configuration.
• iOS App Extension pattern for background processes.
• Modular TS code with clear types and test coverage.
• Persistence via UserDefaults as a lightweight local store.
Detail without overthinking
• How the config-plugin ties node_modules → Xcode targets.
• Persistence in UserDefaults as a shared storage block.
• Don’t omit the DeviceActivitySelectionView (SwiftUI + JS wrapper).