expo-alarm-kit

An Expo module for iOS AlarmKit integration. Schedule native iOS alarms with optional app launch on dismissal or snooze intents.

⚠️ Requirements:

• iOS Deployment Target: 26.0+
• Expo SDK: 50+
• Framework: Apple AlarmKit

Features

• 📅 Schedule Native Alarms: Create alarms that persist even if the app is killed.
• 🔄 Repeating Alarms: Support for weekly repeating schedules.
• 🚀 App Launch Triggers: Optionally launch your app when the user dismisses or snoozes the alarm.
• 🧩 Custom Intent Payloads: Attach optional payload strings for dismiss/snooze events.
• 🎨 Customization: Configure titles, snooze settings, and tint colors.
• 💾 Shared State: Uses App Groups to synchronize alarm state between the system and your app.

---

Installation

npm install expo-alarm-kit
# or
yarn add expo-alarm-kit

Since this module utilizes native iOS frameworks, you must prebuild your project:

npx expo prebuild

---

Configuration (Required)

This module requires native iOS configuration to function. If these steps are skipped, the module will throw errors.

1. Set Deployment Target

In Xcode, navigate to your project's Build Settings and ensure the iOS Deployment Target is set to 26.0 or higher.

❌ Error: Failing to do this will result in a "Module not found: ExpoAlarmKit" error.

2. Add Usage Description

Apple requires you to justify why you need access to alarms.

1. Open your project in Xcode.
2. Select your app target and go to the Info tab.
3. Add a new key: Privacy - Alarm Kit Usage Description.
4. Value: Enter a short description (e.g., "We use alarms to wake you up at your scheduled times.")

3. Configure App Groups

App Groups allow the Alarm extension to communicate with your main application.

1. In Xcode, select your app target.
2. Go to Signing & Capabilities.
3. Click + Capability and select App Groups.
4. Add a new group identifier (e.g., group.com.yourcompany.yourapp).

Important: This identifier must match exactly what you pass to the configure() method in your JavaScript code.

---

Usage

1. Initialization

You must configure the module with your App Group ID as early as possible in your app's lifecycle (e.g., inside App.tsx or _layout.tsx).

import { useEffect } from 'react';
import { configure, getLaunchPayload } from 'expo-alarm-kit';

export default function App() {
  useEffect(() => {
    // 1. Initialize the module
    const isConfigured = configure('group.com.yourcompany.yourapp');
    
    if (!isConfigured) {
      console.error('Failed to configure ExpoAlarmKit. Check App Group ID.');
    }

    // 2. Check if app was launched via an alarm dismiss/snooze intent
    const payload = getLaunchPayload();
    if (payload) {
      console.log('App launched by alarm:', payload.alarmId);
      // Navigate to specific screen or perform action
    }
  }, []);

  return <YourAppContent />;
}

2. Scheduling Alarms

import { 
  scheduleAlarm, 
  scheduleRepeatingAlarm, 
  generateUUID, 
  requestAuthorization 
} from 'expo-alarm-kit';

const handleSchedule = async () => {
  // Always request permission first
  const authStatus = await requestAuthorization();
  if (authStatus !== 'authorized') return;

  // Example: Schedule a one-time alarm for 1 hour from now
  const alarmId = generateUUID();
  
  await scheduleAlarm({
    id: alarmId,
    epochSeconds: Date.now() / 1000 + 3600, 
    title: 'Power Nap Over',
    soundName: 'alarm.wav', // Must be in Xcode bundle resources
    launchAppOnDismiss: true,
    dismissPayload: 'nap-dismiss',
    doSnoozeIntent: true,
    launchAppOnSnooze: true,
    snoozePayload: 'nap-snooze',
    snoozeDuration: 300, // 5 minutes
  });
};

const handleRepeatingSchedule = async () => {
  // Example: Schedule for Mon-Fri at 7:30 AM
  const id = generateUUID();
  
  await scheduleRepeatingAlarm({
    id,
    hour: 7,
    minute: 30,
    weekdays: [2, 3, 4, 5, 6], // 1=Sun, 2=Mon...
    title: 'Work Alarm',
    launchAppOnDismiss: true,
    dismissPayload: 'work-dismiss',
    doSnoozeIntent: true,
    launchAppOnSnooze: false,
    snoozePayload: 'work-snooze',
  });
};

3. Managing Alarms

import { cancelAlarm, getAllAlarms } from 'expo-alarm-kit';

// Get list of active alarm IDs
const activeAlarms = getAllAlarms();

// Cancel a specific alarm
await cancelAlarm('your-alarm-uuid');

---

How It Works

App Groups & Shared Storage

This module relies on iOS App Groups to share UserDefaults between the main app process and the system alarm extension.

• Persistence: When you schedule an alarm, the metadata is written to this shared storage.
• Sync: Both the Native Module and the App Extension read from this same source of truth.

App Launch on Dismiss/Snooze

When launchAppOnDismiss: true or (doSnoozeIntent: true + launchAppOnSnooze: true) is set:

1. The user dismisses or snoozes the alarm on the lock screen.
2. The system launches your app in the background/foreground.
3. The module writes a LaunchPayload to the shared storage.
4. When your React Native JS bundle loads, calling getLaunchPayload() retrieves and clears this data, allowing you to react to the event.

---

API Reference

Configuration & Auth

configure(appGroupIdentifier: string): boolean

Initializes the module. Must be called before other methods.

• Returns: true if the App Group was accessible.

requestAuthorization(): Promise<AuthorizationStatus>

Prompts the user for permission to schedule alarms.

• Returns: 'authorized' | 'denied' | 'notDetermined'

---

Scheduling

scheduleAlarm(options): Promise<boolean>

Schedules a non-repeating alarm.

Options Object:

Property	Type	Required	Description
id	string	Yes	Unique UUID.
epochSeconds	number	No*	Unix timestamp (seconds) for the alarm.
date	Date	No*	Alternative: JS Date object.
title	string	Yes	Main text displayed on lock screen.
soundName	string	No	Filename of sound in app bundle.
launchAppOnDismiss	boolean	No	If true, opens app when stopped.
dismissPayload	string	No	Optional payload string for dismiss intent (null in payload if omitted).
doSnoozeIntent	boolean	No	If true, enables custom snooze intent (default: false).
launchAppOnSnooze	boolean	No	If true, opens app when snooze intent runs.
snoozePayload	string	No	Optional payload string for snooze intent (null in payload if omitted).
stopButtonLabel	string	No	Text for stop button (default: 'Stop').
snoozeButtonLabel	string	No	Text for snooze button.
stopButtonColor	string	No	Hex color string.
snoozeButtonColor	string	No	Hex color string.
tintColor	string	No	Overall UI tint color.
snoozeDuration	number	No	Duration in seconds (default: 540).

*Note: Provide either epochSeconds OR date, not both.

scheduleRepeatingAlarm(options): Promise<boolean>

Schedules a weekly repeating alarm.

Options Object:

Property	Type	Required	Description
id	string	Yes	Unique UUID.
hour	number	Yes	0-23
minute	number	Yes	0-59
weekdays	number[]	Yes	Array of integers: 1 (Sun) to 7 (Sat).
title	string	Yes	Main text displayed.
launchAppOnDismiss	boolean	No	If true, opens app when stopped.
dismissPayload	string	No	Optional payload string for dismiss intent (null in payload if omitted).
doSnoozeIntent	boolean	No	If true, enables custom snooze intent (default: false).
launchAppOnSnooze	boolean	No	If true, opens app when snooze intent runs.
snoozePayload	string	No	Optional payload string for snooze intent (null in payload if omitted).
...	...	...	Supports all visual options from scheduleAlarm.

---

Utilities

cancelAlarm(id: string): Promise<boolean>

Cancels the alarm in AlarmKit and removes it from shared storage.

generateUUID(): string

Helper to generate a unique ID string for new alarms.

getAllAlarms(): string[]

Returns an array of IDs for all currently scheduled alarms.

getLaunchPayload(): LaunchPayload | null

Returns data if the app was launched via an alarm.

interface LaunchPayload {
  alarmId: string;
  payload: string | null;
}

removeAlarm(id: string): void

Advanced: Removes an alarm from local storage records without cancelling the native AlarmKit instance. Use cancelAlarm for standard usage.

---

Known Issues

• Custom Labels/Colors: The stopButtonLabel, stopButtonColor properties are not correctly modifying the stop button/slider.