expo-background-timer v0.2.0
Expo Background Timer Module
The Expo Background Timer Module allows you to schedule and manage timed tasks in your Expo app—even when the app is running in the background. This module supports both Android and iOS, providing a simple API to enable background execution and to set/clear timeouts and intervals.
There is no need to eject your Expo app from an Expo Managed Workflow.
Features
- Schedule and manage multiple timed tasks.
- Reliable execution of tasks in the background.
- Simple API for enabling/disabling background execution and managing timers.
- Emits events to track task and timer status.
Installation
To install the Expo Background Timer Module, run:
npm install expo-background-timer
API
enableBackgroundExecution()
Enables background execution. This sets an internal flag so that when the app enters the background, the module acquires a wake lock (Android) or begins a background task (iOS). Returns a promise that resolves with the task status.
import { enableBackgroundExecution } from "expo-background-timer";
enableBackgroundExecution().then((event) => {
console.log("Background execution enabled:", event.status);
});
disableBackgroundExecution()
Disables background execution. This stops the background task by releasing the wake lock or ending the background task. Returns a promise that resolves with the task status.
import { disableBackgroundExecution } from "expo-background-timer";
disableBackgroundExecution().then((event) => {
console.log("Background execution disabled:", event.status);
});
bgSetTimeout(callback, timeout)
Sets a timeout to execute a callback function after a specified delay (in milliseconds). Returns a unique timeout ID. The module emits an event when the timer starts and when it completes.
import { bgSetTimeout } from "expo-background-timer";
const timeoutId = bgSetTimeout(() => {
console.log("Timeout executed");
}, 5000); // 5 seconds
bgSetInterval(callback, timeout)
Sets an interval to execute a callback function repeatedly after a specified delay (in milliseconds). Returns a unique interval ID. The module emits an event each time the interval callback is executed.
import { bgSetInterval } from "expo-background-timer";
const intervalId = bgSetInterval(() => {
console.log("Interval executed");
}, 10000); // 10 seconds
bgClearTimeout(id)
Clears a timeout set by bgSetTimeout
.
import { bgClearTimeout } from "expo-background-timer";
bgClearTimeout(timeoutId);
bgClearInterval(id)
Clears an interval set by bgSetInterval
.
import { bgClearInterval } from "expo-background-timer";
bgClearInterval(intervalId);
Events
The module emits the following events to keep you informed about background task and timer status:
backgroundTimer.taskStarted
Emitted when a background task is successfully started (e.g., when a wake lock is acquired).backgroundTimer.taskStopped
Emitted when the background task is stopped (e.g., when the wake lock is released).backgroundTimer.started
Emitted when a timer (timeout or interval) is initiated.backgroundTimer.timeout
Emitted when a timeout or interval callback is triggered.backgroundTimer.timeoutCleared
Emitted when a timeout or interval is cleared.backgroundTimer.error
Emitted when an error occurs (e.g., if a background task is already running or a timer cannot be found).
Example
Below is a complete example demonstrating how to use the Expo Background Timer Module:
import React, { useEffect, useState } from "react";
import { Button, StyleSheet, View } from "react-native";
import {
enableBackgroundExecution,
disableBackgroundExecution,
bgSetTimeout,
bgSetInterval,
bgClearTimeout,
bgClearInterval,
} from "expo-background-timer";
let timerCounter = 0;
export default function App() {
useEffect(() => {
// Enable background execution when the app mounts.
enableBackgroundExecution().then((event) => {
console.log("Background execution enabled:", event.status);
});
return () => {
// Disable background execution when the app unmounts.
disableBackgroundExecution().then((event) => {
console.log("Background execution disabled:", event.status);
});
};
}, []);
const [ids, setIds] = useState<number[]>([]);
const onSetTimeout = () => {
console.log("App - onSetTimeout");
const timeoutId = bgSetTimeout(() => {
// Remove the timeout ID from state after execution.
setIds((prevIds) => prevIds.filter((i) => i !== timeoutId));
console.log("Timeout executed");
}, 3000); // 3 seconds
setIds((prevIds) => [...prevIds, timeoutId]);
};
const onSetInterval = () => {
console.log("App - onSetInterval");
const intervalId = bgSetInterval(() => {
timerCounter++;
console.log("Interval executed:", timerCounter);
}, 1000); // 1 second
setIds((prevIds) => [...prevIds, intervalId]);
};
const onStop = (id: number) => {
console.log("App - onStop", id);
setIds((prevIds) => prevIds.filter((i) => i !== id));
bgClearInterval(id);
};
return (
<View style={styles.container}>
<Button title="Set Timeout" onPress={onSetTimeout} />
<Button title="Set Interval" onPress={onSetInterval} />
{ids.map((id) => (
<Button key={id} title={`Stop ${id}`} onPress={() => onStop(id)} />
))}
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: "#fff",
alignItems: "center",
justifyContent: "center",
gap: 10,
},
});
Acknowledgements
This module was heavily inspired by
react-native-background-timer
.
Many thanks to the authors and contributors of that project for their hard work and contributions to the community.
License
This project is licensed under the MIT License.