Exporting to macOS with the WKWebView wrapper



427 visits, 635 views


This tutorial hasn't been translated.


Construct can export your project as a traditional macOS desktop app using WKWebView. This is basically a version of the Safari browser engine that is built in to macOS. In other words it's very much like having your project run in Safari, but without any browser parts like the address bar showing, so it looks like a native app. Also since the exported files don't need to include a full browser engine (like NW.js does), it's a very lightweight export option with minimal file size overhead. This tutorial covers how to use this export option.


Currently, there are no export options specific to the macOS WKWebView export option. However it's important to note that the zip must be extracted on macOS for the app to work properly. If you extract the files on Windows and then copy the files to a macOS device, the app won't work. This is because Windows and macOS understand file permissions differently, and some specific file permissions are required for the app to work. macOS understands these file permissions and so preserves them from the zip, but Windows does not, and so will remove the required file permissions when extracting.

Note that for security reasons, macOS will at first most likely prevent the app from running since it treats it as an untrusted app. You'll see a security warning and the app will not launch. To solve this you will need to notarize the app - for more details see the Distribution section below. However it's possible to work around the security message just for testing purposes. After attempting to run the app and seeing the security message, open System Preferences, and go to the Security & Privacy section. You should see a message there indicating that an app was blocked, and there should be a button that says Open anyway. Click that button and the app should then launch, and be unblocked from running on that specific device. However it still won't run on other devices, which is why you should notarize it for distribution.

WKWebView features

Construct is based on browser technology, but WKWebView does not work exactly the same as a browser. Some of the differences of most interest are:

  • Lightweight export option that does not need to include a copy of an entire browser engine, relying on the system instead
  • WKWebView updates with macOS system updates, so you generally don't need to worry about updates for the browser engine.
  • Some actions which are only allowed after a user input event, such as audio playback and entering fullscreen, can be used unrestricted
  • Navigating to a URL, or opening a URL in a new window, will open the system default browser. This could be a different browser entirely, e.g. Firefox.
  • The Browser 'Close' action exits the app
  • If you enable a theme color in Project Properties, it will be used to tint the window caption


The exported app only uses features built in to macOS, so it does not require anything else to be installed. The minimum supported version of macOS is 10.14 (Mojave), so that version and all newer versions of macOS are supported.

The browser engine used by the app, called WKWebView, is provided by the macOS system. It is based on the version of Safari that originally shipped with macOS. This means installing a newer version of Safari on a macOS system does not update the browser engine used by WKWebView. For example macOS 10.14 originally shipped with Safari 12, and so WKWebView on macOS 10.14 is always based on Safari 12, regardless of whether the Safari browser updated to a newer version. The only way WKWebView updates is via macOS system updates. For example WKWebView on macOS 10.15 (Catalina) is based on Safari 13, and so on.

The exported app supports both Intel and Apple Silicon devices with a universal binary. This means it should run on both kinds of chips without any kind of emulation or performance penalty.

Notarize your app

As mentioned in the Exporting section, before publishing your app you will need to notarize it so other people can run it. For more information refer to Apple's documentation on Notarizing your app before distribution.

If you just want to test the app locally or otherwise want to skip notarization, you can work around the security restriction using System Preferences as described in the Exporting section.


The macOS wrapper export option provides a lightweight option for publishing to macOS, using a system-provided webview to power your game. It's a convenient option since it has a low file size and doesn't require setting up web hosting. Remember to notarize your app before broader distribution.


  • Order by
Want to leave a comment? Login or Register an account!
  • MacOs users need to Unzip it then double click the .app file to run it right?

  • Hello,

    I am getting an error that "your browser does not support or blocks cookies"

    Is there a workaround for this or i am missing something?

    I would like to report that i cannot do the advance minify (the simple one works)

    Error exporting: minify-error

    Shb main.js:2122

    4dc93fd61-5602-45c6-af8b-f8a2ad5496cf:2416 Run main for com/google/javascript/jscomp/CommandLineRunner

    cheerpOS.js:1531 /str/main.js:141:423: ERROR - [JSC_UNDEFINED_VARIABLE] variable RuntimeInterface is undeclared

    141| const exportType=e["exportType"];if(exportType==="windows-uwp"&&typeof Windows!=="undefined")Windows["System"]["Launcher"]["launchUriAsync"](new Windows["Foundation"]["Uri"](url));else if(self["cordova"]&&self["cordova"]["InAppBrowser"])self["cordova"]["InAppBrowser"]["open"](url,"_system");else window.open(url,tag)}}_OnRequestFullscreen(e){if(this._exportType==="windows-webview2"||this._exportType==="macos-wkwebview")...