expo-app-lifecycle-plus 0.1.0

package/.eslintrc.js

@@ -0,0 +1,5 @@
+module.exports = {
+  root: true,
+  extends: ['universe/native', 'universe/web'],
+  ignorePatterns: ['build'],
+};

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright 2025 Adem Hatay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,269 @@
+<a id="readme-top"></a>
+
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+[![MIT License][license-shield]][license-url]
+
+<br />
+<div align="center">
+  <h3 align="center">expo-app-lifecycle-plus</h3>
+
+  <p align="center">
+    Native app lifecycle event module for Expo / React Native on Android and iOS.
+    <br />
+    Android: Process lifecycle + optional activity focus/blur signals
+    <br />
+    iOS: UIApplication + UIScene notifications with inferred termination support
+    <br />
+    <a href="https://github.com/ademhatay/expo-app-lifecycle-plus"><strong>Explore the docs »</strong></a>
+    <br />
+    <br />
+    <a href="https://github.com/ademhatay/expo-app-lifecycle-plus/issues/new?labels=bug">Report Bug</a>
+    ·
+    <a href="https://github.com/ademhatay/expo-app-lifecycle-plus/issues/new?labels=enhancement">Request Feature</a>
+  </p>
+</div>
+
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li>
+      <a href="#about-the-project">About The Project</a>
+      <ul>
+        <li><a href="#built-with">Built With</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#getting-started">Getting Started</a>
+      <ul>
+        <li><a href="#prerequisites">Prerequisites</a></li>
+        <li><a href="#installation">Installation</a></li>
+      </ul>
+    </li>
+    <li><a href="#usage">Usage</a></li>
+    <li><a href="#event-reference">Event Reference</a></li>
+    <li><a href="#api-reference">API Reference</a></li>
+    <li><a href="#platform-notes">Platform Notes</a></li>
+    <li><a href="#troubleshooting">Troubleshooting</a></li>
+    <li><a href="#contributing">Contributing</a></li>
+    <li><a href="#license">License</a></li>
+  </ol>
+</details>
+
+## About The Project
+
+`expo-app-lifecycle-plus` exposes a single event channel and typed payloads so you can observe app state transitions consistently from JavaScript.
+
+It is designed for real-world lifecycle analytics and debugging:
+
+- `addListener((event) => ...)` to stream lifecycle events
+- `getCurrentState()` to read current native state snapshot
+- iOS launch/scene signals and inferred termination support
+- Android process foreground/background and optional activity focus/blur
+
+### Built With
+
+- [Expo Modules](https://docs.expo.dev/modules/overview/)
+- [React Native](https://reactnative.dev/)
+- [AndroidX Lifecycle](https://developer.android.com/topic/libraries/architecture/lifecycle)
+- [UIKit UIApplication Notifications](https://developer.apple.com/documentation/uikit/uiapplication)
+- [UIKit UIScene Notifications](https://developer.apple.com/documentation/uikit/uiscene)
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js LTS (`20` or `22` recommended)
+- Expo / React Native app
+
+### Installation
+
+Expo managed or prebuild:
+
+```bash
+npx expo install expo-app-lifecycle-plus
+```
+
+Bare React Native / Expo bare:
+
+```bash
+npm install expo-app-lifecycle-plus
+# or
+bun add expo-app-lifecycle-plus
+```
+
+Rebuild native apps after install:
+
+```bash
+npx expo run:android
+npx expo run:ios
+```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Usage
+
+```ts
+import * as Lifecycle from 'expo-app-lifecycle-plus';
+
+const current = Lifecycle.getCurrentState();
+console.log('current state', current);
+
+const sub = Lifecycle.addListener((event) => {
+  console.log('lifecycle event', event);
+});
+
+// later
+sub.remove();
+```
+
+### Example Event Payload
+
+```json
+{
+  "type": "foreground",
+  "state": "foreground",
+  "timestamp": 1700000000000,
+  "platform": "ios"
+}
+```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Event Reference
+
+### Common Events
+
+- `jsReload`
+- `coldStart`
+- `foreground`
+- `background`
+
+### iOS Events
+
+- `appLaunch`
+- `active`
+- `inactive`
+- `sceneActive`
+- `sceneInactive`
+- `willTerminate` (best-effort; not guaranteed)
+- `inferredTermination` (emitted on next launch if app was previously backgrounded and appears to have been killed)
+
+### Android Events
+
+- `focusActivity`
+- `blurActivity`
+
+### Event Type
+
+```ts
+type LifecycleEvent = {
+  type:
+    | 'jsReload'
+    | 'coldStart'
+    | 'appLaunch'
+    | 'inferredTermination'
+    | 'foreground'
+    | 'background'
+    | 'active'
+    | 'inactive'
+    | 'willTerminate'
+    | 'sceneActive'
+    | 'sceneInactive'
+    | 'focusActivity'
+    | 'blurActivity';
+  state: 'unknown' | 'foreground' | 'background' | 'active' | 'inactive';
+  timestamp: number;
+  platform: 'ios' | 'android';
+  activity?: string;
+  source?: 'didFinishLaunching' | 'observerStart';
+  inferredFrom?: 'previousBackground';
+  previousBackgroundTimestamp?: number;
+  elapsedSinceBackgroundMs?: number;
+};
+```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## API Reference
+
+### `addListener(listener): EventSubscription`
+
+Subscribes to native lifecycle updates on `onLifecycleEvent`.
+
+```ts
+addListener(listener: (event: LifecycleEvent) => void): EventSubscription
+```
+
+### `getCurrentState(): LifecycleState`
+
+Returns current native lifecycle state snapshot.
+
+```ts
+getCurrentState(): 'unknown' | 'foreground' | 'background' | 'active' | 'inactive'
+```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Platform Notes
+
+- `willTerminate` is not guaranteed on mobile OSes.
+- On iOS, app kills in background may not emit a terminate callback. Use `inferredTermination` for practical analytics.
+- On Android, process lifecycle (`foreground`/`background`) is generally the most reliable signal.
+- `jsReload` can happen during development due to fast refresh/reload and does not always mean a fresh process launch.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Troubleshooting
+
+### I only see `inactive -> background -> foreground -> active`
+
+This is normal lifecycle flow on iOS when app moves between foreground/background.
+
+### `willTerminate` is not emitted
+
+Expected on many real-device scenarios. Mobile OS may kill apps without firing terminate callbacks.
+
+### `coldStart` appears more than once in development
+
+Development reload / fast refresh can recreate JS/runtime state. Use `jsReload` and `appLaunch` together to interpret startup behavior.
+
+### TypeScript import errors
+
+Rebuild package and restart Metro:
+
+```bash
+npm run build
+```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Contributing
+
+PRs and issues are welcome.
+
+1. Fork the project
+2. Create branch
+3. Commit changes
+4. Push branch
+5. Open PR
+
+## License
+
+MIT © Adem Hatay
+
+<!-- MARKDOWN LINKS & IMAGES -->
+[contributors-shield]: https://img.shields.io/github/contributors/ademhatay/expo-app-lifecycle-plus.svg?style=for-the-badge
+[contributors-url]: https://github.com/ademhatay/expo-app-lifecycle-plus/graphs/contributors
+[forks-shield]: https://img.shields.io/github/forks/ademhatay/expo-app-lifecycle-plus.svg?style=for-the-badge
+[forks-url]: https://github.com/ademhatay/expo-app-lifecycle-plus/network/members
+[stars-shield]: https://img.shields.io/github/stars/ademhatay/expo-app-lifecycle-plus.svg?style=for-the-badge
+[stars-url]: https://github.com/ademhatay/expo-app-lifecycle-plus/stargazers
+[issues-shield]: https://img.shields.io/github/issues/ademhatay/expo-app-lifecycle-plus.svg?style=for-the-badge
+[issues-url]: https://github.com/ademhatay/expo-app-lifecycle-plus/issues
+[license-shield]: https://img.shields.io/github/license/ademhatay/expo-app-lifecycle-plus.svg?style=for-the-badge
+[license-url]: https://github.com/ademhatay/expo-app-lifecycle-plus/blob/main/LICENSE

package/android/build.gradle

@@ -0,0 +1,43 @@
+apply plugin: 'com.android.library'
+
+group = 'expo.modules.applifecycleplus'
+version = '0.1.0'
+
+def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+apply from: expoModulesCorePlugin
+applyKotlinExpoModulesCorePlugin()
+useCoreDependencies()
+useExpoPublishing()
+
+// If you want to use the managed Android SDK versions from expo-modules-core, set this to true.
+// The Android SDK versions will be bumped from time to time in SDK releases and may introduce breaking changes in your module code.
+// Most of the time, you may like to manage the Android SDK versions yourself.
+def useManagedAndroidSdkVersions = false
+if (useManagedAndroidSdkVersions) {
+  useDefaultAndroidSdkVersions()
+} else {
+  buildscript {
+    // Simple helper that allows the root project to override versions declared by this library.
+    ext.safeExtGet = { prop, fallback ->
+      rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+    }
+  }
+  project.android {
+    compileSdkVersion safeExtGet("compileSdkVersion", 36)
+    defaultConfig {
+      minSdkVersion safeExtGet("minSdkVersion", 24)
+      targetSdkVersion safeExtGet("targetSdkVersion", 36)
+    }
+  }
+}
+
+android {
+  namespace "expo.modules.applifecycleplus"
+  defaultConfig {
+    versionCode 1
+    versionName "0.1.0"
+  }
+  lintOptions {
+    abortOnError false
+  }
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest>
+</manifest>

package/android/src/main/java/expo/modules/applifecycleplus/ExpoAppLifecyclePlusModule.kt

@@ -0,0 +1,91 @@
+package expo.modules.applifecycleplus
+
+import android.app.Activity
+import android.app.Application
+import android.os.Bundle
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.ProcessLifecycleOwner
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class ExpoAppLifecyclePlusModule : Module(), DefaultLifecycleObserver, Application.ActivityLifecycleCallbacks {
+  private var didSendStartupEvents = false
+  private var currentState: String = "unknown"
+  private var application: Application? = null
+
+  override fun definition() = ModuleDefinition {
+    Name("ExpoAppLifecyclePlus")
+
+    Events("onLifecycleEvent")
+
+    OnCreate {
+      ProcessLifecycleOwner.get().lifecycle.addObserver(this@ExpoAppLifecyclePlusModule)
+
+      val app = appContext.reactContext?.applicationContext as? Application
+      application = app
+      app?.registerActivityLifecycleCallbacks(this@ExpoAppLifecyclePlusModule)
+    }
+
+    OnStartObserving {
+      if (!didSendStartupEvents) {
+        didSendStartupEvents = true
+        send("jsReload")
+        send("coldStart")
+      }
+    }
+
+    Function("getCurrentState") {
+      currentState
+    }
+
+    OnDestroy {
+      ProcessLifecycleOwner.get().lifecycle.removeObserver(this@ExpoAppLifecyclePlusModule)
+      application?.unregisterActivityLifecycleCallbacks(this@ExpoAppLifecyclePlusModule)
+      application = null
+    }
+  }
+
+  private fun send(type: String, extra: Map<String, Any?> = emptyMap()) {
+    currentState = when (type) {
+      "foreground", "active" -> "foreground"
+      "background", "inactive" -> "background"
+      else -> currentState
+    }
+
+    val payload = mutableMapOf<String, Any?>(
+      "type" to type,
+      "state" to currentState,
+      "timestamp" to System.currentTimeMillis(),
+      "platform" to "android"
+    )
+    payload.putAll(extra)
+    sendEvent("onLifecycleEvent", payload)
+  }
+
+  override fun onStart(owner: LifecycleOwner) {
+    send("foreground")
+  }
+
+  override fun onStop(owner: LifecycleOwner) {
+    send("background")
+  }
+
+  override fun onActivityResumed(activity: Activity) {
+    send("focusActivity", mapOf("activity" to activity.javaClass.simpleName))
+  }
+
+  override fun onActivityPaused(activity: Activity) {
+    send("blurActivity", mapOf("activity" to activity.javaClass.simpleName))
+  }
+
+  override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}
+
+  override fun onActivityStarted(activity: Activity) {}
+
+  override fun onActivityStopped(activity: Activity) {}
+
+  override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) {}
+
+  override fun onActivityDestroyed(activity: Activity) {}
+}

package/build/ExpoAppLifecyclePlus.types.d.ts

@@ -0,0 +1,17 @@
+export type LifecycleEventType = 'jsReload' | 'coldStart' | 'appLaunch' | 'inferredTermination' | 'foreground' | 'background' | 'active' | 'inactive' | 'willTerminate' | 'sceneActive' | 'sceneInactive' | 'focusActivity' | 'blurActivity';
+export type LifecycleState = 'unknown' | 'foreground' | 'background' | 'active' | 'inactive';
+export type LifecycleEvent = {
+    type: LifecycleEventType;
+    state: LifecycleState;
+    timestamp: number;
+    platform: 'ios' | 'android';
+    activity?: string;
+    source?: 'didFinishLaunching' | 'observerStart';
+    inferredFrom?: 'previousBackground';
+    previousBackgroundTimestamp?: number;
+    elapsedSinceBackgroundMs?: number;
+};
+export type ExpoAppLifecyclePlusModuleEvents = {
+    onLifecycleEvent: (event: LifecycleEvent) => void;
+};
+//# sourceMappingURL=ExpoAppLifecyclePlus.types.d.ts.map

package/build/ExpoAppLifecyclePlus.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpoAppLifecyclePlus.types.d.ts","sourceRoot":"","sources":["../src/ExpoAppLifecyclePlus.types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,WAAW,GACX,WAAW,GACX,qBAAqB,GACrB,YAAY,GACZ,YAAY,GACZ,QAAQ,GACR,UAAU,GACV,eAAe,GACf,aAAa,GACb,eAAe,GACf,eAAe,GACf,cAAc,CAAC;AAEnB,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,YAAY,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE7F,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,kBAAkB,CAAC;IACzB,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,KAAK,GAAG,SAAS,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,oBAAoB,GAAG,eAAe,CAAC;IAChD,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG;IAC7C,gBAAgB,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CACnD,CAAC"}

package/build/ExpoAppLifecyclePlus.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ExpoAppLifecyclePlus.types.js.map

package/build/ExpoAppLifecyclePlus.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpoAppLifecyclePlus.types.js","sourceRoot":"","sources":["../src/ExpoAppLifecyclePlus.types.ts"],"names":[],"mappings":"","sourcesContent":["export type LifecycleEventType =\n  | 'jsReload'\n  | 'coldStart'\n  | 'appLaunch'\n  | 'inferredTermination'\n  | 'foreground'\n  | 'background'\n  | 'active'\n  | 'inactive'\n  | 'willTerminate'\n  | 'sceneActive'\n  | 'sceneInactive'\n  | 'focusActivity'\n  | 'blurActivity';\n\nexport type LifecycleState = 'unknown' | 'foreground' | 'background' | 'active' | 'inactive';\n\nexport type LifecycleEvent = {\n  type: LifecycleEventType;\n  state: LifecycleState;\n  timestamp: number;\n  platform: 'ios' | 'android';\n  activity?: string;\n  source?: 'didFinishLaunching' | 'observerStart';\n  inferredFrom?: 'previousBackground';\n  previousBackgroundTimestamp?: number;\n  elapsedSinceBackgroundMs?: number;\n};\n\nexport type ExpoAppLifecyclePlusModuleEvents = {\n  onLifecycleEvent: (event: LifecycleEvent) => void;\n};\n"]}

package/build/ExpoAppLifecyclePlusModule.d.ts

@@ -0,0 +1,8 @@
+import { NativeModule } from 'expo';
+import { ExpoAppLifecyclePlusModuleEvents, LifecycleState } from './ExpoAppLifecyclePlus.types';
+declare class ExpoAppLifecyclePlusModule extends NativeModule<ExpoAppLifecyclePlusModuleEvents> {
+    getCurrentState(): LifecycleState;
+}
+declare const _default: ExpoAppLifecyclePlusModule;
+export default _default;
+//# sourceMappingURL=ExpoAppLifecyclePlusModule.d.ts.map

package/build/ExpoAppLifecyclePlusModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpoAppLifecyclePlusModule.d.ts","sourceRoot":"","sources":["../src/ExpoAppLifecyclePlusModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAuB,MAAM,MAAM,CAAC;AAEzD,OAAO,EAAE,gCAAgC,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEhG,OAAO,OAAO,0BAA2B,SAAQ,YAAY,CAAC,gCAAgC,CAAC;IAC7F,eAAe,IAAI,cAAc;CAClC;;AAED,wBAAuF"}

package/build/ExpoAppLifecyclePlusModule.js

@@ -0,0 +1,3 @@
+import { requireNativeModule } from 'expo';
+export default requireNativeModule('ExpoAppLifecyclePlus');
+//# sourceMappingURL=ExpoAppLifecyclePlusModule.js.map

package/build/ExpoAppLifecyclePlusModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpoAppLifecyclePlusModule.js","sourceRoot":"","sources":["../src/ExpoAppLifecyclePlusModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,mBAAmB,EAAE,MAAM,MAAM,CAAC;AAQzD,eAAe,mBAAmB,CAA6B,sBAAsB,CAAC,CAAC","sourcesContent":["import { NativeModule, requireNativeModule } from 'expo';\n\nimport { ExpoAppLifecyclePlusModuleEvents, LifecycleState } from './ExpoAppLifecyclePlus.types';\n\ndeclare class ExpoAppLifecyclePlusModule extends NativeModule<ExpoAppLifecyclePlusModuleEvents> {\n  getCurrentState(): LifecycleState;\n}\n\nexport default requireNativeModule<ExpoAppLifecyclePlusModule>('ExpoAppLifecyclePlus');\n"]}

package/build/index.d.ts

@@ -0,0 +1,6 @@
+import { EventSubscription } from 'expo-modules-core';
+import { LifecycleEvent, LifecycleState } from './ExpoAppLifecyclePlus.types';
+export * from './ExpoAppLifecyclePlus.types';
+export declare function addListener(listener: (event: LifecycleEvent) => void): EventSubscription;
+export declare function getCurrentState(): LifecycleState;
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGtD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAE9E,cAAc,8BAA8B,CAAC;AAE7C,wBAAgB,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,iBAAiB,CAExF;AAED,wBAAgB,eAAe,IAAI,cAAc,CAEhD"}

package/build/index.js

@@ -0,0 +1,9 @@
+import Module from './ExpoAppLifecyclePlusModule';
+export * from './ExpoAppLifecyclePlus.types';
+export function addListener(listener) {
+    return Module.addListener('onLifecycleEvent', listener);
+}
+export function getCurrentState() {
+    return Module.getCurrentState();
+}
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,MAAM,MAAM,8BAA8B,CAAC;AAGlD,cAAc,8BAA8B,CAAC;AAE7C,MAAM,UAAU,WAAW,CAAC,QAAyC;IACnE,OAAO,MAAM,CAAC,WAAW,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,MAAM,CAAC,eAAe,EAAE,CAAC;AAClC,CAAC","sourcesContent":["import { EventSubscription } from 'expo-modules-core';\n\nimport Module from './ExpoAppLifecyclePlusModule';\nimport { LifecycleEvent, LifecycleState } from './ExpoAppLifecyclePlus.types';\n\nexport * from './ExpoAppLifecyclePlus.types';\n\nexport function addListener(listener: (event: LifecycleEvent) => void): EventSubscription {\n  return Module.addListener('onLifecycleEvent', listener);\n}\n\nexport function getCurrentState(): LifecycleState {\n  return Module.getCurrentState();\n}\n"]}

package/expo-module.config.json

@@ -0,0 +1,9 @@
+{
+  "platforms": ["apple", "android", "web"],
+  "apple": {
+    "modules": ["ExpoAppLifecyclePlusModule"]
+  },
+  "android": {
+    "modules": ["expo.modules.applifecycleplus.ExpoAppLifecyclePlusModule"]
+  }
+}

package/ios/ExpoAppLifecyclePlus.podspec

@@ -0,0 +1,29 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'ExpoAppLifecyclePlus'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.description    = package['description']
+  s.license        = package['license']
+  s.author         = package['author']
+  s.homepage       = package['homepage']
+  s.platforms      = {
+    :ios => '15.1',
+    :tvos => '15.1'
+  }
+  s.swift_version  = '5.9'
+  s.source         = { git: 'https://github.com/ademhatay/expo-app-lifecycle-plus' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  # Swift/Objective-C compatibility
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+  }
+
+  s.source_files = "**/*.{h,m,mm,swift,hpp,cpp}"
+end

package/ios/ExpoAppLifecyclePlusModule.swift

@@ -0,0 +1,167 @@
+import ExpoModulesCore
+import UIKit
+
+public class ExpoAppLifecyclePlusModule: Module {
+  private var didSendStartupEvents = false
+  private var didSendAppLaunch = false
+  private var observers: [NSObjectProtocol] = []
+  private var currentState = "unknown"
+  private let defaults = UserDefaults.standard
+  private let pendingBackgroundKey = "expo.appLifecyclePlus.pendingBackground"
+  private let backgroundTimestampKey = "expo.appLifecyclePlus.backgroundTimestamp"
+
+  public func definition() -> ModuleDefinition {
+    Name("ExpoAppLifecyclePlus")
+
+    Events("onLifecycleEvent")
+
+    OnCreate {
+      self.currentState = self.readApplicationState()
+      let center = NotificationCenter.default
+
+      self.observers.append(center.addObserver(
+        forName: UIApplication.didBecomeActiveNotification,
+        object: nil,
+        queue: .main
+      ) { _ in
+        self.clearBackgroundMarker()
+        self.send(type: "active", nextState: "active")
+      })
+
+      self.observers.append(center.addObserver(
+        forName: UIApplication.willResignActiveNotification,
+        object: nil,
+        queue: .main
+      ) { _ in self.send(type: "inactive", nextState: "inactive") })
+
+      self.observers.append(center.addObserver(
+        forName: UIApplication.willEnterForegroundNotification,
+        object: nil,
+        queue: .main
+      ) { _ in self.send(type: "foreground", nextState: "foreground") })
+
+      self.observers.append(center.addObserver(
+        forName: UIApplication.didEnterBackgroundNotification,
+        object: nil,
+        queue: .main
+      ) { _ in
+        self.markEnteredBackground()
+        self.send(type: "background", nextState: "background")
+      })
+
+      self.observers.append(center.addObserver(
+        forName: UIApplication.willTerminateNotification,
+        object: nil,
+        queue: .main
+      ) { _ in
+        self.clearBackgroundMarker()
+        self.send(type: "willTerminate")
+      })
+
+      self.observers.append(center.addObserver(
+        forName: UIApplication.didFinishLaunchingNotification,
+        object: nil,
+        queue: .main
+      ) { _ in
+        self.emitAppLaunch(source: "didFinishLaunching")
+      })
+
+      self.observers.append(center.addObserver(
+        forName: UIScene.didActivateNotification,
+        object: nil,
+        queue: .main
+      ) { _ in self.send(type: "sceneActive") })
+
+      self.observers.append(center.addObserver(
+        forName: UIScene.willDeactivateNotification,
+        object: nil,
+        queue: .main
+      ) { _ in self.send(type: "sceneInactive") })
+    }
+
+    OnStartObserving {
+      if !self.didSendStartupEvents {
+        self.didSendStartupEvents = true
+        self.send(type: "jsReload")
+        self.send(type: "coldStart")
+        self.emitAppLaunch(source: "observerStart")
+      }
+    }
+
+    Function("getCurrentState") {
+      self.currentState
+    }
+
+    OnDestroy {
+      let center = NotificationCenter.default
+      self.observers.forEach { center.removeObserver($0) }
+      self.observers.removeAll()
+    }
+  }
+
+  private func emitAppLaunch(source: String) {
+    if didSendAppLaunch {
+      return
+    }
+    didSendAppLaunch = true
+    send(type: "appLaunch", extra: ["source": source])
+    emitInferredTerminationIfNeeded()
+  }
+
+  private func markEnteredBackground() {
+    defaults.set(true, forKey: pendingBackgroundKey)
+    defaults.set(Int(Date().timeIntervalSince1970 * 1000), forKey: backgroundTimestampKey)
+  }
+
+  private func clearBackgroundMarker() {
+    defaults.set(false, forKey: pendingBackgroundKey)
+  }
+
+  private func emitInferredTerminationIfNeeded() {
+    guard defaults.bool(forKey: pendingBackgroundKey) else {
+      return
+    }
+
+    let nowMs = Int(Date().timeIntervalSince1970 * 1000)
+    let lastBackgroundAt = defaults.integer(forKey: backgroundTimestampKey)
+    let elapsedMs = lastBackgroundAt > 0 ? nowMs - lastBackgroundAt : nil
+
+    send(
+      type: "inferredTermination",
+      extra: [
+        "inferredFrom": "previousBackground",
+        "previousBackgroundTimestamp": lastBackgroundAt > 0 ? lastBackgroundAt : nil,
+        "elapsedSinceBackgroundMs": elapsedMs
+      ]
+    )
+    clearBackgroundMarker()
+  }
+
+  private func readApplicationState() -> String {
+    switch UIApplication.shared.applicationState {
+    case .active:
+      return "active"
+    case .inactive:
+      return "inactive"
+    case .background:
+      return "background"
+    @unknown default:
+      return "unknown"
+    }
+  }
+
+  private func send(type: String, nextState: String? = nil, extra: [String: Any?] = [:]) {
+    if let nextState {
+      self.currentState = nextState
+    }
+
+    var payload: [String: Any?] = [
+      "type": type,
+      "state": self.currentState,
+      "timestamp": Int(Date().timeIntervalSince1970 * 1000),
+      "platform": "ios"
+    ]
+    extra.forEach { payload[$0.key] = $0.value }
+    sendEvent("onLifecycleEvent", payload)
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "expo-app-lifecycle-plus",
+  "version": "0.1.0",
+  "description": "this module handle manage app states",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "scripts": {
+    "build": "expo-module build",
+    "clean": "expo-module clean",
+    "lint": "expo-module lint",
+    "test": "expo-module test",
+    "prepare": "expo-module prepare",
+    "prepublishOnly": "expo-module prepublishOnly",
+    "expo-module": "expo-module",
+    "open:ios": "xed example/ios",
+    "open:android": "open -a \"Android Studio\" example/android"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "expo-app-lifecycle-plus",
+    "ExpoAppLifecyclePlus"
+  ],
+  "repository": "https://github.com/ademhatay/expo-app-lifecycle-plus",
+  "bugs": {
+    "url": "https://github.com/ademhatay/expo-app-lifecycle-plus/issues"
+  },
+  "author": "Adem Hatay <hatayadem5@gmail.com> (https://github.com/ademhatay)",
+  "license": "MIT",
+  "homepage": "https://github.com/ademhatay/expo-app-lifecycle-plus#readme",
+  "dependencies": {},
+  "devDependencies": {
+    "@types/react": "~19.1.0",
+    "expo-module-scripts": "^5.0.8",
+    "expo": "^54.0.27",
+    "react-native": "0.81.5"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "react": "*",
+    "react-native": "*"
+  }
+}

package/src/ExpoAppLifecyclePlus.types.ts

@@ -0,0 +1,32 @@
+export type LifecycleEventType =
+  | 'jsReload'
+  | 'coldStart'
+  | 'appLaunch'
+  | 'inferredTermination'
+  | 'foreground'
+  | 'background'
+  | 'active'
+  | 'inactive'
+  | 'willTerminate'
+  | 'sceneActive'
+  | 'sceneInactive'
+  | 'focusActivity'
+  | 'blurActivity';
+
+export type LifecycleState = 'unknown' | 'foreground' | 'background' | 'active' | 'inactive';
+
+export type LifecycleEvent = {
+  type: LifecycleEventType;
+  state: LifecycleState;
+  timestamp: number;
+  platform: 'ios' | 'android';
+  activity?: string;
+  source?: 'didFinishLaunching' | 'observerStart';
+  inferredFrom?: 'previousBackground';
+  previousBackgroundTimestamp?: number;
+  elapsedSinceBackgroundMs?: number;
+};
+
+export type ExpoAppLifecyclePlusModuleEvents = {
+  onLifecycleEvent: (event: LifecycleEvent) => void;
+};

package/src/ExpoAppLifecyclePlusModule.ts

@@ -0,0 +1,9 @@
+import { NativeModule, requireNativeModule } from 'expo';
+
+import { ExpoAppLifecyclePlusModuleEvents, LifecycleState } from './ExpoAppLifecyclePlus.types';
+
+declare class ExpoAppLifecyclePlusModule extends NativeModule<ExpoAppLifecyclePlusModuleEvents> {
+  getCurrentState(): LifecycleState;
+}
+
+export default requireNativeModule<ExpoAppLifecyclePlusModule>('ExpoAppLifecyclePlus');

package/src/index.ts

@@ -0,0 +1,14 @@
+import { EventSubscription } from 'expo-modules-core';
+
+import Module from './ExpoAppLifecyclePlusModule';
+import { LifecycleEvent, LifecycleState } from './ExpoAppLifecyclePlus.types';
+
+export * from './ExpoAppLifecyclePlus.types';
+
+export function addListener(listener: (event: LifecycleEvent) => void): EventSubscription {
+  return Module.addListener('onLifecycleEvent', listener);
+}
+
+export function getCurrentState(): LifecycleState {
+  return Module.getCurrentState();
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+// @generated by expo-module-scripts
+{
+  "extends": "expo-module-scripts/tsconfig.base",
+  "compilerOptions": {
+    "outDir": "./build"
+  },
+  "include": ["./src"],
+  "exclude": ["**/__mocks__/*", "**/__tests__/*", "**/__rsc_tests__/*"]
+}