Give up Mac Catalyst, Rewrite with Native Code

5 min readApr 24, 2022


Scaffolding photo created by jcomp — freepik

I wrote an app for iOS called MermaidEditor, which is an editor app for writing mermaid js diagram, it uses WKWebVIew to load a Monaco editor for editing the source code of mermaid js diagram with support of syntax highlighting and keyword auto completion.

After releasing the iOS version of MermaidEditor, I wanted to bring this app to macOS, and I thought it was the best scenario using Mac Catalyst, a technology provided by Apple that allows us make our iPad app work on macOS with a single checkbox tick.

So I built MermaidEditor for macOS with Mac Catalyst, and released it to users. But after some releases, I decided to rewrite it in native code.


Minimum macOS Requirement

The minimum macOS deployment target version required by Mac Catalyst is macOS 10.15, so if our application targets a macOS version earlier than macOS 10.15, it will not work.

Also, Mac Catalyst has a limitation that if we want the application to be more like a native desktop application, we should select “Optimize Interface for Mac” in Mac Catalyst deployment options.

Aha, the minimum macOS deployment target version upgraded to macOS 11 Big Sur!

Therefore, if you want to keep your applications compatible with more macOS versions, you should not use Mac Catalyst.

Missing Document-based Architecture

MermaidEditor is a document editor app, so I used UIDocumentBrowser as the base application architecture, it provides a lot file management features on iOS.

The first problem I faced when bring MermaidEditor to macOS was that UIDocumentBrowser didn’t work the way I expected it to. It displays a blank window, and then opens a document picker for user to choose a file to open, which is different than the native NSDocument class behaves.

But this is not the biggest problem.

The biggest problem is that the Cocoa Document-based application architecture provided a lot feature for application that related to document opening, editing, etc. such as:

  • NSDocument for document opening, saving, versioning
  • Window controller with renaming, duplicating, editing state indicator
  • Tabbed window support

Therefore, if your application is geared towards document editing, you should not use Mac Catalyst.

Different SplitView Controller

I used split view in MermaidEditor to support editing with two panels, which are synchronized mermaid js source editing panel and diagram image preview panel.

On iOS, I used UISplitViewController, which works well enough on iPad, but on macOS, it has some limitations and is not suitable for a native desktop application.

With NSSplitViewController, the split bar can be resized to any position in the split view, but UISplitViewController limits the size of primary column to certain range, and it does not allow two panels to be resized to any size.

So, if your application requires two panels in split view, you should not use Mac Catalyst.

Strange Behavior in WKWebView

In MermaidEditor, it includes a monaco editor from Microsoft to provide major editor features such as syntax highlighting, keyword auto completion.

The monaco editor is a web-based editor, so it requires webview to work in the application.

Because monaco editor uses custom code rendering architecture, the text area of editor is not the typical textarea tag in HTML. So monaco editor provide a manual button to acquire keyboard focus on iOS.

But on macOS, there is no such button in monaco editor, because monaco editor recognizes the environment of the web view as a desktop computer. That will result in keyboard actions not being captured in Mac Catalyst, which has a blinking cursor, but you can not do anything in the editor.

This means that if you need embed a monaco editor in your application, you should not use Mac Catalyst.

Hard to Handle Mouse Event

MermaidEditor has a diagram image preview panel to check rendered diagram instantly, users can check detail of the diagram image by zoom or pan gestures., But on macOS, usually the user uses mouse to control everything.

UIScrollView in Mac Catalyst will have some default behaviors like scrolling content with scroll wheel, clicking and dragging to move the content offset, but if we want some different like zooming diagram image with scroll wheel?

That is impossible in Mac Catalyst, because there is no mouse events on iOS.

So, if your application requires mouse events such as scroll wheel events or mouse move events, you should not use Mac Catalyst.


Mac Catalyst has so many limitations, and if you want build an application with more native application experience, you should not use Mac Catalyst.

However, Mac Catalyst is a short way to adapting an iOS app to macOS, if you already have an application on iOS, and do not touch the limitations above, you should have a try with Mac Catalyst.

Though Mac Catalyst does not provide the full desktop application experience, much of the code can be shared between iOS and macOS, and we only need to write different code for scaffold and UI controls.

With Mac Catalyst, we can see that Apple has done a lot to smooth out the gap between iOS and macOS. Maybe someday in the future, iOS will have a desktop experience and then UIKit will provide more desktop features.

Thanks for reading.