⌚️📱 rn-watch-connect

A React Native module that enables smooth and reliable communication between an iOS app and its paired Apple Watch using Apple’s WatchConnectivity framework. This library offers an easy-to-use interface for sending messages, transferring files, syncing data, and monitoring the connection status between the iPhone and Apple Watch — all from a React Native app.

⚠️ Note: This module does NOT provide a way to build Apple Watch apps. A separate Watch app must still be developed using Swift or SwiftUI. This package is intended as a modern, actively maintained alternative to the previously available (but now outdated) React Native watch connectivity module.

🙌 Contributions are welcome! If you'd like to improve the module or add new features, feel free to open an issue or submit a pull request.

🚀 Installation

npm install rn-watch-connect
# or
yarn add rn-watch-connect

✨ Features

• 📶 Monitor watch connectivity status
• 💬 Send messages between iPhone and Apple Watch
• 📂 Transfer files between iPhone and Apple Watch
• 🔄 Sync data between iPhone and Apple Watch
• 📡 Event-based communication
• 🧠 TypeScript support with generic types
• 📩 Promise-based message sending with reply support

📚 API Reference

Properties

| Property | Type | Description | | ------------------------------ | ------------------------------- | ---------------------------------------------------------- | | isWatchSupported | boolean | Indicates if the device supports Watch Connectivity | | isWatchPaired | boolean | Indicates if an Apple Watch is paired with the device | | isWatchAppInstalled | boolean | Indicates if the Watch app is installed | | isWatchReachable | boolean | Indicates if the paired Watch is currently reachable | | watchActivationState | string | Current activation state of the Watch Connectivity session | | applicationContext | { [key: string]: any } | Current application context | | receivedApplicationContext | { [key: string]: any } | Received application context from the Watch | | outstandingUserInfoTransfers | OutstandingUserInfoTransfer[] | Outstanding user info transfers | | outstandingFileTransfers | FileTransfer[] | Outstanding file transfers |

📡 Methods

sendMessage<T, R>(message: T): Promise<R>

Sends a message to the paired Apple Watch and waits for a reply.

Type Parameters:

• T: Type of the message to send (defaults to Record<string, any>)
• R: Type of the expected reply (defaults to Record<string, any>)

Parameters:

• message: The message to send to the Watch

Returns:

• Promise<R>: A promise that resolves with the Watch's reply

Note: The following delegate method is expected to receive the message on the receiver app

• On Counter app (receiver):

  func session(_ session: WCSession, didReceiveMessage message: [String : Any], replyHandler: @escaping ([String : Any]) -> Void)

Example:

type MyMessage = {
  message: string;
};

type MyReply = {
  response: string;
};

const reply = await RnWatchConnect.sendMessage<MyMessage, MyReply>({
  message: "Hello from iPhone!",
});

sendMessageWithoutReply<T>(message: T): Promise<void>

Sends a message to the paired Apple Watch without expecting a reply.

Type Parameters:

• T: Type of the message to send (defaults to Record<string, any>)

Parameters:

• message: The message to send to the Watch

Note: The following delegate method is expected to receive the message on the receiver app

• On Watch app (receiver):

  func session(_ session: WCSession, didReceiveMessage message: [String : Any])

Example:

await RnWatchConnect.sendMessageWithoutReply({
  message: "Hello from iPhone!",
});

replyToMessage(replyId: string, reply: Record<string, any>): void

Sends a reply to a message received from the Watch.

Parameters:

• replyId: The ID of the message to reply to
• reply: The reply message to send

Example:

RnWatchConnect.replyToMessage(replyId, {
  response: "Hello from iPhone!",
});

sendDataMessage(data: string): Promise<string>

Sends a base64 encoded data message to the paired Apple Watch and waits for a reply.

Parameters:

• data: A base64 encoded string to send to the Watch

Returns:

• Promise<string>: A promise that resolves with the Watch's base64 encoded reply

Note: The following delegate method is expected to receive the message on the receiver app

• On Watch app (receiver):

  func session(_ session: WCSession, didReceiveMessageData messageData: Data, replyHandler: @escaping (Data) -> Void)

Example:

try {
  const reply = await RnWatchConnect.sendDataMessage(
    "SGVsbG8gZnJvbSBpUGhvbmUh"
  ); // "Hello from iPhone!" in base64
  console.log("Decoded reply:", Buffer.from(reply, "base64").toString());
} catch (error) {
  console.log("Error:", error);
}

sendDataMessageWithoutReply(data: string): Promise<void>

Sends a base64 encoded data message to the paired Apple Watch without expecting a reply.

Parameters:

• data: A base64 encoded string to send to the Watch

Note: The following delegate method is expected to receive the message on the receiver app

• On Watch app (receiver):

  func session(_ session: WCSession, didReceiveMessageData messageData: Data)

Example:

try {
  await RnWatchConnect.sendDataMessageWithoutReply("SGVsbG8gZnJvbSBpUGhvbmUh");
} catch (error) {
  console.log("Error:", error);
}

replyToDataMessage(replyId: string, response: string): void

Sends a reply to a data message received from the Watch.

Parameters:

• replyId: The ID of the message to reply to
• response: The base64 encoded response string

Example:

RnWatchConnect.replyToDataMessage(
  event.replyId,
  "TWVzc2FnZSByZWNlaXZlZCBvbiBSZWFjdCBOYXRpdmUh"
);

updateApplicationContext<T>(applicationContext: T): Promise<void>

Updates the application context on the Watch.

Parameters:

• applicationContext: The application context to update (defaults to Record<string, any>)

Example:

await RnWatchConnect.updateApplicationContext({
  theme: "red",
});

transferUserInfo<T>(userInfo: T): UserInfoTransfer

Transfers user info to the Watch.

Parameters:

• userInfo: The user info to transfer (defaults to Record<string, any>)

Returns:

• UserInfoTransfer: The transfer ID and isTransferring status

Example:

const transfer = RnWatchConnect.transferUserInfo({
  message: "Hello from iPhone!",
});

cancelUserInfoTransfer(transferId: string): { id: string }

Cancels a pending user info transfer.

Parameters:

• transferId: The ID of the transfer to cancel

Returns:

• { id: string }: The transfer ID

Example:

RnWatchConnect.cancelUserInfoTransfer(transfer.id);

transferFile(file: string, metadata?: Record<string, any>): FileTransfer

Transfers a file to the Watch.

Parameters:

• file: The file URL to transfer
• metadata: The metadata to transfer (defaults to Record<string, any>) (optional)

Returns:

• FileTransfer: Object containing the transfer information

Example:

const transfer = RnWatchConnect.transferFile("file://path/to/file.txt", {
  name: "file.txt",
});

cancelFileTransfer(transferId: string): { id: string }

Cancels a pending file transfer.

Parameters:

• transferId: The ID of the transfer to cancel

Returns:

• { id: string }: The transfer ID

Example:

RnWatchConnect.cancelFileTransfer(transfer.id);

📡 Events

onMessageReceived

Triggered when a message is received from the Watch. It doesn't require a response. The event object is the message object received from the Watch.

Example:

useEventListener(RnWatchConnect, "onMessageReceived", (event) => {
  console.log("Message received:", event);
});

onMessageWithReply

Triggered when a message requiring a reply is received from the Watch. The event object is an object with the following properties:

• message: The message object received from the Watch
• replyId: The ID of the message to reply to

Example:

useEventListener(RnWatchConnect, "onMessageWithReply", (event) => {
  console.log("Message received:", event.message);
  RnWatchConnect.replyToMessage(event.replyId, {
    response: "Reply from iPhone",
  });
});

onDataMessageReceived

Triggered when a data message is received from the Watch. The event object is an object with the following properties:

• data: The base64 encoded data received from the Watch

Example:

useEventListener(RnWatchConnect, "onDataMessageReceived", (event) => {
  console.log("Data message received:", event.data);
});

onDataMessageWithReply

Triggered when a data message requiring a reply is received from the Watch. The event object is an object with the following properties:

• data: The base64 encoded data received from the Watch
• replyId: The ID of the message to reply to

Example:

useEventListener(RnWatchConnect, "onDataMessageWithReply", (event) => {
  console.log("Data message received:", event.data);
  RnWatchConnect.replyToDataMessage(event.replyId, "SGVsbG8gZnJvbSBpUGhvbmUh");
});

onUserInfoReceived

Triggered when user info is received from the Watch. The event object is the user info object received from the Watch.

Example:

useEventListener(RnWatchConnect, "onUserInfoReceived", (event) => {
  console.log("User info received:", event);
});

onFileReceived

Triggered when a file is received from the Watch. The event object is an object with the following properties:

• File: The file object received from the Watch

Example:

useEventListener(RnWatchConnect, "onFileReceived", (event) => {
  console.log("File received:", event);
});

onReachabilityChanged

Triggered when the Watch's reachability status changes.

Example:

useEventListener(
  RnWatchConnect,
  "onReachabilityChanged",
  ({ isWatchReachable }) => {
    console.log("Watch reachability changed:", isWatchReachable);
  }
);

onWatchPairedChanged

Triggered when the Watch pairing status changes.

Example:

useEventListener(
  RnWatchConnect,
  "onWatchPairedChanged",
  ({ isWatchPaired }) => {
    console.log("Watch paired status changed:", isWatchPaired);
  }
);

onWatchAppInstallChanged

Triggered when the Watch app installation status changes.

Example:

useEventListener(
  RnWatchConnect,
  "onWatchAppInstallChanged",
  ({ isWatchAppInstalled }) => {
    console.log("Watch app installation status changed:", isWatchAppInstalled);
  }
);

onApplicationContextChanged

Triggered when the application context changes.

Example:

useEventListener(
  RnWatchConnect,
  "onApplicationContextChanged",
  (applicationContext) =>
    console.log("Application context changed:", applicationContext)
);

Types

OutstandingUserInfoTransfer

| Property | Type | Description | | -------------- | ------------------- | --------------------------------------------- | | id | string | Unique identifier for the transfer | | userInfo | Record<string, any> | The user info payload being transferred | | isTransferring | boolean | Whether the transfer is currently in progress |

UserInfoTransfer

| Property | Type | Description | | -------------- | ------- | --------------------------------------------- | | id | string | Unique identifier for the transfer | | isTransferring | boolean | Whether the transfer is currently in progress |

FileTransfer

| Property | Type | Description | | -------------- | ------------ | --------------------------------------------- | | id | string | Unique identifier for the transfer | | isTransferring | boolean | Whether the transfer is currently in progress | | progress | FileProgress | The progress of the file transfer | | file | File | The file being transferred |

File

| Property | Type | Description | | -------- | ------------------- | ------------------------------------- | | fileURL | string | The URL of the file being transferred | | metadata | Record<string, any> | The metadata associated with the file |

FileProgress

| Property | Type | Description | | ------------------ | ------ | --------------------------------------------------------- | | fractionCompleted | number | The fraction of the file transfer that has been completed | | completedUnitCount | number | The number of bytes transferred so far | | totalUnitCount | number | The total number of bytes to be transferred |

TypeScript Support

The module is fully typed and supports generic types for messages and replies. You can define your own types for messages and replies:

// Define your message types
type MyMessage = {
  message: string;
  // ... other properties
};

type MyReply = {
  response: string;
  // ... other properties
};

// Use them in your code
const reply = await RnWatchConnect.sendMessage<MyMessage, MyReply>({
  message: "Hello",
});

📄 License

MIT