How to build an Apple Watch app: watchOS setup, iPhone integration, HealthKit, testing and release

Summary. An Apple Watch app is its own platform target, not a shrunken iPhone screen. Choose the architecture first: watch-only, a companion that depends on the iPhone, or an independent companion that works without it. With Xcode 27.x you build against the watchOS 27 SDK, deploy to watchOS 9 to 27, and debug on devices running watchOS 10 or later. Since 28 April 2026, uploads must be built with Xcode 26 and the watchOS 26 SDK or later. From April 2027 the watchOS 27 SDK will be required. This guide covers each step, from project setup to Watch Connectivity, HealthKit workouts, background limits, testing and App Store release, with code we have checked against the current SDK.

Building an Apple Watch app means its own target, bundle identity, lifecycle, signing, deployment target, runtime limits and interface conventions. Depending on the product, it may also need Watch Connectivity, HealthKit, background execution, WidgetKit, notifications, networking, authentication or a backend.

For teams adding a watch app to an existing iPhone app, the first question is not how to add a target. It is this: should the watch app depend on the iPhone, work on its own, or exist only on the watch? That decision shapes the project structure, sign-in, data sync, permissions, testing and what people can do when the iPhone is out of reach.

About this article. This guide is based on Apple's Xcode, watchOS, Watch Connectivity, HealthKit, WatchKit, WidgetKit, App Store and Human Interface Guidelines documentation, as checked on 17 October 2026. We type-checked every code sample against the watchOS 27 SDK with Swift 6.4. Researched with AI assistance and reviewed by our editorial team.

What you need before you start

At minimum you need a Mac that runs Xcode and the watchOS SDK you plan to use. You also need:

• An Apple Account for installing builds on your own devices. A free account is enough to run apps on your own watch, and HealthKit and background modes work without the paid programme. Distribution, TestFlight, push notifications, CloudKit and Sign in with Apple need the Apple Developer Program, at 99 USD a year in local currency where available; in India you enrol through the Apple Developer app.

• An iPhone and an Apple Watch for anything that needs real hardware.

• HealthKit privacy descriptions for health features.

• App IDs, capabilities, signing and provisioning set up for each target.

• A backend or CloudKit plan if the watch must work on its own.

Which watches you are building for

Separate three questions: your minimum watchOS deployment target, the APIs you need, and which watches can run that combination. For watchOS 27, Apple lists Apple Watch SE 3, Series 9 to 12 and Ultra 2 to 4, paired with an iPhone 11 or later or an iPhone SE (2nd generation or later) running iOS 27. An app that targets an older watchOS reaches older watches too, as long as the APIs it uses exist there.

Xcode and watchOS version requirements

Apple publishes several different numbers, and they are easy to mix up:

Xcode 27.1 shipped on 15 October 2026 with the same values. A project can therefore target watchOS 9 while you develop with Xcode 27, but you can only install and debug directly on watches running watchOS 10 or later.

App Store submission requirements

Since 28 April 2026, apps uploaded to App Store Connect must be built with Xcode 26 or later using the watchOS 26 SDK for watchOS apps. Apple has also announced that from April 2027 watchOS apps must be built with the watchOS 27 SDK or later. watchOS uploads must also include 64-bit support; Apple recommends keeping the default Standard architectures build setting.

Keep two values in your build documentation: the oldest watchOS your app supports, and the Xcode and SDK version Apple currently accepts for upload.

Choose the watch app architecture

This is the most important decision in the project. Apple's documentation describes three kinds of product.

Watch-only app. The app exists only on Apple Watch, with its own interface, networking, HealthKit, notifications and data. Use it when there is no meaningful iPhone companion.

Dependent companion app. The watch experience is part of an iPhone product. The watch app installs on the watch, but people cannot launch it until the iOS app has finished installing. This suits a watch app that extends the iPhone experience.

Independent companion app. People can install and use the watch app without the iPhone app. Its important functions must work on the watch alone: creating an account and signing in, granting permissions, and getting data directly. It can still use Watch Connectivity when the iPhone is around, but not as its main source of data.

                                START
                      │
                      ▼
            Do you have an iOS app?
                 /          \
               NO            YES
               │              │
               ▼              ▼
         Watch-only      Add a watch target
                              │
                              ▼
                 Must the watch work without
                  the iPhone app installed?
                         /       \
                       YES        NO
                        │          │
                        ▼          ▼
                  Independent   Dependent
          

To turn a dependent companion into an independent one, select the watch app target and turn on Supports Running Without iOS App Installation under General, Deployment Info.

The development flow

A watch project usually runs in this order:

1. Write down what people must be able to do on the wrist.

1. Choose the architecture and the minimum watchOS version.

1. Create the project or add a watch target.

1. Set bundle IDs, signing and capabilities.

1. Build the SwiftUI interface.

1. Choose the data path: Watch Connectivity, HealthKit, your own server or CloudKit.

1. Add background work, notifications and complications where needed.

1. Test in Simulator, then on a real iPhone and watch.

1. Archive, test through TestFlight and submit.

For a fitness app, the middle of that flow is HealthKit's workout machinery: a workout session, a live workout builder collecting heart rate, energy and distance, and a workout saved to HealthKit and synced to the iPhone or your backend.

Create a new watchOS project

In Xcode, choose File, New, Project, then the watchOS App template. Apple's templates offer a Watch-only App or a Watch App with New Companion iOS App. The watch-only template still creates an iOS stub target that acts as a wrapper, but nothing installs on the iPhone.

Treat the watch app as its own platform target with its own build configuration, not as a view inside the iPhone target.

Add a watch app to an existing iPhone app

This is the most common case. Add a target, choose watchOS, App, then Watch App for Existing iOS App, and pick the iOS app it belongs to. Then set the watch target's bundle ID, signing, deployment target and capabilities, and keep watch-specific code in it.

Flutter apps: Runner is not the watch app

A Flutter iOS project has an iOS target named Runner. Adding Apple Watch support does not turn Runner into the watch app. The watch app is a separate native target written in Swift and SwiftUI, using Watch Connectivity, HealthKit or WidgetKit as needed, and it talks to the Flutter iPhone app through native code and a platform channel. Dart cannot replace the native watch target, and most Flutter plug-ins have no watchOS implementation, so check each package before you rely on it.

The coding layer

A clean structure keeps the interface, state, services and platform APIs apart:

            Watch App
├── App/            WatchApp.swift
├── Features/
│   ├── Dashboard/  DashboardView, DashboardViewModel
│   ├── Workout/    WorkoutView, WorkoutViewModel, WorkoutManager
│   └── Settings/   SettingsView
├── Services/       ConnectivityService, HealthKitService, APIService
├── Models/         Workout, UserProfile
└── Shared/         Constants
          

The exact folders are your choice; the separation is what matters. A view talks to a view model, which uses a service, which calls the Apple framework or your backend.

A basic SwiftUI watch app

            import SwiftUI

@main
struct FitnessWatchApp: App {
    var body: some Scene {
        WindowGroup {
            DashboardView()
        }
    }
}

struct DashboardView: View {
    @State private var isWorkoutActive = false

    var body: some View {
        VStack(spacing: 12) {
            Text("Today's Activity")
                .font(.headline)

            Button(isWorkoutActive ? "Stop Workout" : "Start Workout") {
                isWorkoutActive.toggle()
            }
        }
        .padding()
    }
}
          

Share business logic carefully

If the iPhone and watch apps share rules, put pure Swift code in a shared Swift package used by both targets. Network models and validation often share well, and API clients can if every dependency supports watchOS. UIKit-only code cannot, and an iPhone-only package will stop the watch target from building, so check each package's supported platforms first.

Connect the iPhone and the watch

Watch Connectivity provides two-way communication between an iOS app and its paired watchOS app, through WCSession. It offers four ways to send data:

A message sent from the watch wakes the iOS app, but a message sent from the iPhone does not wake the watch app. Activate the session before you send anything, and check its activation state. On iOS, also check that a watch is paired and your watch app is installed.

            import WatchConnectivity

final class ConnectivityService: NSObject, WCSessionDelegate {

    func start() {
        guard WCSession.isSupported() else { return }
        let session = WCSession.default
        session.delegate = self
        session.activate()
    }

    func sendWorkoutState(_ state: String) {
        let session = WCSession.default
        guard session.activationState == .activated, session.isReachable else { return }

        session.sendMessage(
            ["state": state],
            replyHandler: { reply in print("Reply: \(reply)") },
            errorHandler: { error in print("Send failed: \(error)") }
        )
    }

    // Required on iOS and watchOS.
    nonisolated func session(_ session: WCSession,
                             activationDidCompleteWith activationState: WCSessionActivationState,
                             error: Error?) {
        if let error { print("Activation failed: \(error)") }
    }

    // The receiver must implement this when the sender passes a reply handler.
    nonisolated func session(_ session: WCSession,
                             didReceiveMessage message: [String: Any],
                             replyHandler: @escaping ([String: Any]) -> Void) {
        replyHandler(["received": true])
    }

    #if os(iOS)
    // Required in the iOS app to support switching between paired watches.
    nonisolated func sessionDidBecomeInactive(_ session: WCSession) {}
    nonisolated func sessionDidDeactivate(_ session: WCSession) {
        WCSession.default.activate()
    }
    #endif
}
          

The iOS delegate methods matter. Without them, Apple says the app opts out of supporting more than one Apple Watch. Delegate callbacks arrive on a background thread, which is why they are marked nonisolated; move to the main actor before you touch the interface.

The other three transfers follow the same rule: check activation first.

            let session = WCSession.default
guard session.activationState == .activated else { return }
#if os(iOS)
guard session.isPaired, session.isWatchAppInstalled else { return }
#endif
session.transferUserInfo(["workoutId": "12345", "status": "completed"])
do { try session.updateApplicationContext(["goal": 8500, "steps": 6320]) } catch { print(error) }
let transfer = session.transferFile(fileURL, metadata: ["type": "workout"])  // fileURL: a local file
          

Watch Connectivity is a communication framework, not your database. An independent app cannot depend on it, and the counterpart app may not be installed or nearby, so choose each API by whether the exchange is interactive, state-based, queued or a file.

Build a fitness or HealthKit app

Fitness apps are more complex because HealthKit and workout sessions bring system-managed health data and background execution.

Add the HealthKit capability

Select the watch target, open Signing & Capabilities and add HealthKit. Add NSHealthShareUsageDescription for data you read and NSHealthUpdateUsageDescription for data you write. Without them, the app crashes when it asks for authorisation. Any app that uses HealthKit also needs a privacy policy.

            import HealthKit

final class HealthKitService {
    private let healthStore = HKHealthStore()

    func requestAuthorization() async throws {
        guard HKHealthStore.isHealthDataAvailable() else { return }

        let workoutType = HKObjectType.workoutType()
        let readTypes: Set<HKObjectType> = [HKQuantityType(.heartRate), workoutType]
        let shareTypes: Set<HKSampleType> = [workoutType]

        try await healthStore.requestAuthorization(toShare: shareTypes, read: readTypes)
    }
}
          

Request only the types you need. The older HKObjectType.quantityType(forIdentifier:) form is marked deprecated in the watchOS 27.2 beta SDK, so use HKQuantityType(.heartRate) in new code.

HealthKit privacy works differently

People grant or deny each data type separately, and your app cannot tell whether read access was denied: HealthKit deliberately hides the difference between full access and denied access. In watchOS 27, people can also grant only a recent window of history. Call earliestAuthorizedSampleDate(for:) after authorisation and use it to bound your queries. Before you save data, check authorizationStatus(for:). Treat permission as runtime state, not a one-time event.

Workout apps use a different runtime model

A workout-tracking app uses HKWorkoutConfiguration, HKWorkoutSession, HKLiveWorkoutBuilder and HKLiveWorkoutDataSource. The flow: the person taps Start, you create a configuration and session, the live builder collects heart rate, energy and distance, the interface shows it, and you save the workout when it ends.

            import HealthKit

final class WorkoutManager: NSObject,
                            HKWorkoutSessionDelegate,
                            HKLiveWorkoutBuilderDelegate {

    private let healthStore = HKHealthStore()
    private var session: HKWorkoutSession?
    private var builder: HKLiveWorkoutBuilder?

    func startWorkout() async throws {
        let configuration = HKWorkoutConfiguration()
        configuration.activityType = .running
        configuration.locationType = .outdoor

        let workoutSession = try HKWorkoutSession(healthStore: healthStore,
                                                  configuration: configuration)
        let workoutBuilder = workoutSession.associatedWorkoutBuilder()
        workoutBuilder.dataSource = HKLiveWorkoutDataSource(healthStore: healthStore,
                                                            workoutConfiguration: configuration)
        workoutSession.delegate = self
        workoutBuilder.delegate = self
        session = workoutSession
        builder = workoutBuilder

        let start = Date()
        workoutSession.startActivity(with: start)
        try await workoutBuilder.beginCollection(at: start)  // without this, nothing is collected
    }

    func stopWorkout() {
        session?.stopActivity(with: Date())  // finish in the .stopped callback below
    }

    nonisolated func workoutSession(_ workoutSession: HKWorkoutSession,
                                    didChangeTo toState: HKWorkoutSessionState,
                                    from fromState: HKWorkoutSessionState,
                                    date: Date) {
        guard toState == .stopped else { return }
        let builder = workoutSession.associatedWorkoutBuilder()
        builder.endCollection(withEnd: date) { success, _ in
            guard success else { return }
            builder.finishWorkout { _, _ in  // saves the workout to HealthKit
                workoutSession.end()
            }
        }
    }

    nonisolated func workoutSession(_ workoutSession: HKWorkoutSession,
                                    didFailWithError error: Error) {
        print("Workout session failed: \(error)")
    }

    nonisolated func workoutBuilder(_ workoutBuilder: HKLiveWorkoutBuilder,
                                    didCollectDataOf collectedTypes: Set<HKSampleType>) {
        // Read workoutBuilder.statistics(for:) and publish to the UI on the main actor.
    }

    nonisolated func workoutBuilderDidCollectEvent(_ workoutBuilder: HKLiveWorkoutBuilder) {}
}
          

The ending sequence matters: stop the activity, wait for the stopped state, end collection, finish the workout, which saves it, then end the session. A real app also needs HealthKit authorisation to share workouts, the HealthKit capability, and the Workout processing background mode. Add the Audio background mode as well if the workout plays audio or haptics. Start the session while the app is in the foreground; it keeps running when the app moves to the background. watchOS may suspend a workout that uses too much CPU in the background.

Apple's workout guidelines add interface rules: show clearly that a session is running, let people save or discard it, confirm a save and discard very short sessions.[^hig-workouts]

Multidevice workouts

If the same workout must appear live on the watch and the iPhone, use HealthKit's multidevice support. Apple's sample shows how to mirror a workout from the watch to its companion iOS app, using startMirroringToCompanionDevice() on watchOS 10 or later, with two-way communication between them. Since iOS 26, the iPhone can also run its own workout session.

Use Watch Connectivity for ordinary app data, HealthKit workout APIs for tracking, and the multidevice architecture for a shared live workout, rather than streaming sensor data over Watch Connectivity.

Networking, offline behaviour and independent apps

An independent app cannot use the iPhone as its only data source. Apple says it should download its own data, using CloudKit or your own server. That gives three architectures: requests that go through the iPhone, the watch calling your backend directly, or CloudKit shared by both devices.

There is one important exception for health products. App Review guideline 5.1.3(ii) says apps may not store personal health information in iCloud. For workout or health data, use your own server, not CloudKit.

Watch network requests can go through the paired iPhone, a known Wi-Fi network or cellular, so test all three routes, and use a background URLSession for transfers that may outlive the app's time on screen. Design the data layer to show cached data when a request fails:

            enum DashboardState { case loading, loaded(Dashboard, isStale: Bool), offline }

@MainActor
final class DashboardModel {
    var state: DashboardState = .loading
    let api: DashboardAPI      // fetchDashboard() async throws -> Dashboard
    let cache: DashboardCache  // readDashboard() -> Dashboard?, save(_:)

    init(api: DashboardAPI, cache: DashboardCache) { self.api = api; self.cache = cache }

    func loadDashboard() async {
        let cached = cache.readDashboard()
        if let cached { state = .loaded(cached, isStale: true) }

        do {
            let fresh = try await api.fetchDashboard()
            cache.save(fresh)
            state = .loaded(fresh, isStale: false)
        } catch {
            if cached == nil { state = .offline }  // keep showing cached data if we have it
        }
    }
}
          

Authentication on Apple Watch

A dependent app can rely on the iPhone for setup. An independent app cannot: account creation, sign-in, token storage, permissions and the first data download must all work on the watch. Options include Sign in with Apple and your own sign-in form. If the watch app lets people create an account, App Review also requires a way to delete it inside the app. If you call the app independent, people must be able to finish onboarding on the watch.

Background execution and runtime limits

A watch app is suspended soon after the person lowers their wrist. Apple provides specific mechanisms for work that must continue:

Background tasks give an app only a few seconds each, and only if it has a complication on the active watch face. Extended runtime session types include self care and mindfulness, which run while the app is frontmost, and physical therapy and smart alarm, which can run in the background. Pick the mechanism for the job; a generic background task is the wrong tool for a workout app.

Build the interface for the watch

Apple describes watchOS apps as focused on quick actions through brief interactions. A good watch interaction is: open, understand at once, take one action, get feedback, move on. A running screen that shows distance, time and heart rate with one Pause button beats a menu of dashboard, stats, nutrition, friends, goals and history.

Digital Crown, Action button, double tap and widgets

Depending on your target watchOS version, consider:

• The Digital Crown for scrolling and moving through metrics.

• The Action button on Apple Watch Ultra, which can start a workout through the App Intents StartWorkoutIntent.

• Double tap, available in watchOS 11 and later, to trigger a view's primary action through handGestureShortcut(.primaryAction). Apple advises against setting a primary action in views with lists or scroll views.

• App Intents and Siri actions for quick tasks.

Add a feature only when it solves a real interaction problem.

Widgets and complications

Watch complications are built with WidgetKit: accessory widgets also appear as complications and in the Smart Stack. Use RelevanceKit to tell the system when your widget is relevant for the Smart Stack. Widgets update through timelines and can also receive updates through push notifications.

ClockKit has been deprecated since watchOS 10, and Apple keeps it only for supporting watchOS 8 and earlier. Xcode 27's minimum deployment target is watchOS 9, so new projects should use WidgetKit. A complication should show the small piece of information people need before they open the app, not a miniature copy of it.

Notifications

A watch app can use local and remote notifications. An independent app can receive push notifications directly on the watch, including complication pushes. For a companion app, Apple recommends sending the same notification to both the watch and the paired iPhone; the system shows it only once. Health and fitness apps should keep notifications rare: the wrist is a high-attention surface.

Testing and debugging

Work up a testing ladder: SwiftUI previews, the watchOS Simulator, the iPhone and watch Simulators together, a physical iPhone and watch, TestFlight, then release.

Some features do not work in Simulator. Apple says the Simulator does not support transferUserInfo(_:), and file transfers need real devices too. Xcode 27's Device Hub can pair an iPhone and a watch running iOS 27 and watchOS 27 over the network, which Apple says makes watch pairing more reliable.

Test these on a real watch at minimum:

• pairing behaviour and Watch Connectivity transfers;

• navigation and Digital Crown input;

• notifications;

• HealthKit permissions, workout sessions and sensor data;

• background behaviour and battery impact;

• networking with weak or no connection;

• launch, resume and independent installation where relevant.

Debug the two processes separately

A companion product is two apps. A failure can sit in the iOS app, in Watch Connectivity, in the watch app, in HealthKit, in background execution or in your backend. Log each boundary, such as the iOS app sending state, the session queuing the transfer, the watch receiving it and the interface updating, and synchronisation bugs become much easier to find.

Signing, bundle IDs and capabilities

The watch target has its own bundle identifier, team, signing, deployment target and capabilities: push notifications, HealthKit, background modes and a widget extension, each only if needed. For a companion app, the watch app's WKCompanionAppBundleIdentifier must match the iOS app's bundle identifier. Do not copy the iPhone target's capabilities to the watch by default; add each one because a watch feature needs it.

TestFlight and App Store release

After development: archive in Xcode, then in the Organizer choose Validate App and Distribute App to upload. Test through TestFlight with internal and external testers, then submit for review. External testing needs your first build approved by Beta App Review. TestFlight allows up to 100 internal and 10,000 external testers.

Before you upload, check bundle identifiers, signing, the deployment target, HealthKit configuration, privacy descriptions and policy, notification setup, watch screenshots, widget and complication setup, app icons and the production backend. App Store Connect requires Apple Watch screenshots for watch apps.

App Review has rules that hit watch apps in particular:

• Display advertising is not allowed in watchOS apps (2.5.18).

• HealthKit data may not be used for advertising or data mining (5.1.3(i)).

• Apps must not write false data to HealthKit or store personal health information in iCloud (5.1.3(ii)).

• An app in the Health and Fitness or Medical category that is distributed in the EEA, UK or US must declare whether it is a regulated medical device. Existing apps that have not declared by early 2027 cannot submit updates.

Inspect the final archive, not just the project settings, to confirm it contains the watch app, entitlements, bundle IDs and architectures you expect.

A practical fitness app architecture

For an iOS fitness app adding Apple Watch support, a scalable split looks like this:

The watch should not become a dumping ground for every iPhone feature.

How complexity varies

These are informal engineering planning categories, not Apple ratings or cost estimates. Our article on when a watchOS 27 app is worth building covers the business case, and our watchOS 27 features guide covers what changed for users.

Common architecture mistakes

• Making Watch Connectivity the database. It is a transport; an independent app needs its own source of truth.

• Streaming workout sensor data over Watch Connectivity. HealthKit's workout APIs exist for that.

• Storing health data in CloudKit. App Review forbids personal health information in iCloud.

• Treating the watch as a small iPhone. Design for short, glanceable interactions.

• Testing only in Simulator. Transfers, workouts, sensors, pairing and battery need real devices.

• An independent app that needs the iPhone. Its important functions must work alone.

• Adding every capability. Add each one because a feature needs it.

How eCorpIT can help

eCorpIT is a Gurugram-based technology organisation, founded in 2021, assessed at CMMI Level 5 and MSME certified, with senior-led engineering teams working across AWS, Microsoft and Google platforms. Our iOS team builds Apple Watch apps and adds watch targets to existing iPhone and Flutter apps, including HealthKit workouts, Watch Connectivity, complications and App Store release, through our iOS app development service. Talk to us at /contact-us/.

Last updated: 17 October 2026.

References

1. Creating independent watchOS apps — Apple Developer Documentation

1. SDK and system requirements — Xcode, Apple Developer

1. Upcoming requirements — Apple Developer

1. Submitting — App Store, Apple Developer

1. Program enrollment — Apple Developer Account Help

1. Supported capabilities (watchOS) — Apple Developer Account Help

1. watchOS 27 — Apple

1. Xcode 27 Release Notes — Apple Developer Documentation

1. New 64-bit requirement for watchOS apps — Apple Developer News

1. Setting up a watchOS project — Apple Developer Documentation

1. WCSession — Apple Developer Documentation

1. sendMessage(_:replyHandler:errorHandler:) — Apple Developer Documentation

1. Protecting user privacy — HealthKit, Apple Developer Documentation

1. Authorizing access to health data — Apple Developer Documentation

1. Running workout sessions — Apple Developer Documentation

1. Enabling background sessions — Apple Developer Documentation

1. Building a multidevice workout app — Apple Developer Documentation

1. App Review Guidelines — Apple Developer

1. Keeping your watchOS app's content up to date — Apple Developer Documentation

1. Authenticating users on Apple Watch — Apple Developer Documentation

1. Using background tasks — Apple Developer Documentation

1. Using extended runtime sessions — Apple Developer Documentation

1. watchOS apps — Apple Developer Documentation

1. StartWorkoutIntent — Apple Developer Documentation

1. Gestures — Apple Human Interface Guidelines

1. Creating accessory widgets and watch complications — Apple Developer Documentation

1. RelevanceKit — Apple Developer Documentation

1. ClockKit — Apple Developer Documentation

1. registerForRemoteNotifications() — Apple Developer Documentation

1. transferUserInfo(_:) — Apple Developer Documentation

1. WKCompanionAppBundleIdentifier — Apple Developer Documentation

1. Distributing your app for beta testing and releases — Apple Developer Documentation

1. TestFlight — Apple Developer

1. Screenshot specifications — App Store Connect Help

1. Update on regulated medical device apps in the EEA, UK and US — Apple Developer News