An Introductory Guide to Porting Your App to visionOS

With the introduction of visionOS, Apple has ushered in a new era of “Spatial Computing” for app developers. This innovative operating system presents a unique set of opportunities and challenges as developers seek to adapt their existing iOS or iPadOS apps to this new platform. Porting an app to visionOS requires a deep understanding of the old and new operating systems, a clear strategy, and a willingness to adapt. This guide explores some challenges you might encounter during porting and provides practical tips and techniques to navigate these hurdles effectively

How to port your App to visionOS

1. Understand your app’s use case on visionOS

With the introduction of visionOS, Apple has ushered in a new era of “Spatial Computing” for app developers. This innovative operating system presents a unique set of opportunities and challenges as developers seek to adapt their existing iOS or iPadOS apps to this new platform. Porting an app to visionOS requires a deep understanding of the old and new operating systems, a clear strategy, and a willingness to adapt. This guide explores some challenges you might encounter during porting and provides practical tips and techniques to navigate these hurdles effectively.

2. Understanding the Challenges in Porting to visionOS

Porting an existing app to visionOS can be a complex task due to several significant differences between iOS or iPadOS and visionOS. Here are some key challenges you may face:

1. Visual Style Differences:
   VisionOS has a distinct visual style compared to iOS and iPadOS. The rendering of navigation elements, standard controls, and other interface elements varies between these operating systems. Suppose your app’s design or functionality makes too many assumptions about iOS or iPadOS styles or deviates heavily from iOS’s “native” design language. In that case, you will likely encounter a variety of visual glitches or an interface that looks very out of place on visionOS.
2. API Compatibility Issues:
   While many iOS and iPadOS frameworks and APIs work on visionOS “out of the box”, there are also some significant differences. Many APIs and Frameworks deprecated in prior versions of iOS have been removed entirely from visionOS. During the beta period, we also found non-deprecated APIs that worked perfectly fine on iOS that caused unexplained crashes on visionOS. These inconsistencies can lead to unexpected issues during the porting process and require rewriting or uplifting significant parts of an app’s functionality. These issues could be more challenging in older app codebases.
3. Dependency on Third-Party Libraries:
   Porting to visionOS could be significantly more difficult if your app relies on third-party libraries. Not all libraries have been updated to support visionOS. You might need to wait for library authors to update their code, or you might need to modify the libraries yourself. Updating binary-only or proprietary dependencies to have visionOS compatibility is more challenging as you must wait for vendors to do this work or remove the dependency from your app.
4. Package Managers & Build Tools:
   To ensure smooth porting to visionOS, you must update tools like Cocoapods to the latest versions. Other tools might need to be updated to support the visionOS platform, causing further complications. We recommend transitioning away from Cocoapods to Swift Package Manager where possible and reducing your dependency on third-party tooling.

Bonus: Practical Strategies for a Smooth Porting Experience

Despite these challenges, several strategies can make the porting process easier and more efficient:

1. Upgrade Your Dependencies:
   Before starting the porting process, update all your third-party library and tool dependencies to their latest versions. Doing so will help avoid potential compatibility issues during the porting process.
2. Start with “Designed for iPhone” and “Designed for iPad” Modes:
   A practical first step is to ensure your app functions in the “Designed for iPhone” or “Designed for iPad” modes on visionOS. This step helps identify and rectify significant compatibility issues before delving into the complexities of visionOS-specific UI. Apple provides good guidance on how to check whether your existing app is compatible with visionOS. Much of this guidance aligns with what is already best practice for developing an iPadOS application, such as:
   1. Avoid assuming the device type or idiom is always an iPhone, iPad, or iPod Touch.
   2. Support iPad and iPhone in the same app, organise your interface using scenes, avoid accessing screen details, and design your windows and views to resize dynamically.
   3. Prepare your app to handle unavailable hardware or features and to function on devices with varying numbers of displays and windows.
   4. Don’t make assumptions based on the available frameworks or symbols.
   5. Don’t assume your app runs in the background or that background apps are always hidden.
3. Adhere to Apple’s Guidelines:
   Apple provides a comprehensive guide on bringing your existing apps to visionOS. Following this guide can help prevent common pitfalls during the porting process. They offer recommendations on:
   1. Cleaning up legacy code and removing deprecated APIs and frameworks.
   2. Isolating features or subsystems that are unavailable or behave differently on visionOS.
   3. Updating your app’s interface and assets to take advantage of visionOS specifics.
4. Leverage SwiftUI:
   Applications written in SwiftUI are generally easier to port than UIKit apps. SwiftUI encourages you to describe your app’s layout and user interface semantically, allowing the SwiftUI framework to adapt and automatically present platform-specific options when appropriate.

Final Thoughts

While porting your existing app to visionOS can be complex and challenging, it is manageable. You can navigate this process smoothly and effectively by understanding the challenges, following a systematic approach, adhering to Apple’s guidelines and best practices, and leveraging modern tools and techniques.