Exporting desktop apps with NW.js

13

Features on these Courses

Stats

16,970 visits, 22,351 views

Tools

Translations

This tutorial hasn't been translated.

License

This tutorial is licensed under CC BY 4.0. Please refer to the license text if you wish to reuse, share or remix the content contained within this tutorial.

Published on 11 Oct, 2017. Last updated 23 May, 2022

Construct can export your project as a traditional desktop app with NW.js, which is basically a standalone version of the Google Chrome browser. In other words it's very much like having your project run in Chrome, but without the user needing to have Chrome installed on their computer, and without the browser parts showing like the address bar so it looks like a native app. This tutorial covers how to use this export option.

NW.js exports Linux, macOS and Windows desktop apps. Both 32-bit and 64-bit variants are available for Linux and Windows. macOS only provides a 64-bit build, since all modern Mac systems are already 64-bit.

Alternative desktop exports

Since NW.js bundles a copy of the entire Chromium browser engine, the size of the exported files will be relatively large, adding perhaps 80-90mb per platform. If you'd like to try a more lightweight option for Windows and macOS, see Exporting to Windows with the WebView2 wrapper and Exporting to macOS with the WKWebView wrapper.

Downloading NW.js versions

Construct automatically downloads NW.js when you export. Each NW.js version is based off an equivalent Chrome release, so the corresponding versions are also listed (under the name Chromium, which is the browser engine that powers both Chrome and NW.js). By default Construct will always use the latest version available.

NW.js downloads are also saved locally so each version only needs to be downloaded once. Since the downloads can be large, you may wish to download an NW.js version in the background ahead of time. You can do this by clicking the Manage versions... link in the NW.js options dialog to open the NW.js version manager. You can also download platforms individually skipping the ones you're not interested in, as well as delete old NW.js downloads to free up space.

NW.js specific features

Desktop apps have unique privileges not normally available from web apps, such as the ability to write files directly to disk. The NW.js object allows you to use such features. Remember however if you ever want to port your project to a different platform, none of the NW.js object features will work. You may need to disable some functionality or use other features instead. It may be easier to design your project to be portable from the start; for example Local Storage and savegames work on all platforms, whereas writing files to disk will only work with NW.js.

Fullscreen mode

To run NW.js exports in fullscreen mode, as with other platforms use the Browser object's Request fullscreen action. Normally in a browser this cannot be used automatically, and requires a user input event to work; however it can work automatically in NW.js. Therefore you can use Request fullscreen in On start of layout to automatically put an NW.js game in to fullscreen mode.

Export options

When exporting to NW.js, there are a number of options available to customise the app. For more information see the manual entry for the NW.js options dialog.

Advanced users can specify custom command-line options for the Chromium engine that powers NW.js apps. An unofficial list of the possible command-line options - of which there are a great many - is available on this website.

Publishing on Windows

When publishing Windows apps, NW.js only fully supports GPU-accelerated rendering if the latest DirectX runtime components are installed. The exported dxwebsetup.exe file installs these if they are not already present on a user's system. You should ensure this is installed on user's systems before running your project, for example by creating an installer for your game that runs the file as one of the installation steps. You can pass the /Q parameter to the dxwebsetup.exe installer to run in "quiet" mode (where it runs automatically without prompting the user). Note if the user does not have the latest DirectX runtime components installed, the game may fall back to a software rendering, which can perform poorly. If users still experience issues after installing dxwebsetup.exe, especially crashes, poor performance or graphical glitches, encourage them to update their graphics driver since many issues can arise from out-of-date drivers.

Updating Windows app icons

For technical reasons it's difficult for Construct to set Windows app icons from inside the browser. Instead a tool named WindowsIconUpdater.exe is exported with your files. All you need to do is extract all the files in the zip to a local folder, run WindowsIconUpdater.exe, and your executable icons should switch to use the ones in your Construct project.

Publishing on macOS and Linux

When publishing to macOS and Linux, it's important to preserve the file permissions. The exported files for NW.js require various permissions and links to be set up in order to work correctly on macOS and Linux. File permissions work slightly differently across operating systems. For example Windows generally recognises any file ending in .exe as something that can be run. On macOS and Linux, executable files have no special file extension, and instead requiring an "executable" file permission to be set. Windows is not usually aware of this, so if you copy files from Windows to a macOS or Linux system, the files may not have execute permission and therefore fail to run. There are a number of other cases where file permissions can be lost depending on the way files are transferred and the source and destination operating system.

To mitigate this, Construct sets all the right permissions for files inside the zip file. Upon extracting the zip file, the permissions are all preserved correctly. This means:

  • It is safe to transfer the exported zip file by any means.
  • Once the zip file is extracted, the files should not be transferred to another system, because the permissions might be lost.

In short, this means you should only extract the exported zip file on the target operating system. For example if you export a macOS app using a Windows system, you should transfer the exported zip file to the macOS system, and then extract it using macOS. This ensures the file permissions are preserved. If you extracted the zip on Windows and then transferred the extracted files to macOS, it could break the app.

macOS security restrictions

Modern versions of macOS won't run an untrusted app. 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.

Locally testing an unsigned app

The security restrictions on macOS can be worked around for local testing only. This gets the app to work on one specific device, but it still won't work on other devices - as mentioned you'll need to notarize the app for wider distribution. However these steps can help with testing.

Apple Silicon devices

On devices with Apple Silicon, such as the M1 chip, the app must be signed otherwise macOS will refuse to run it at all. It's possible to use an ad-hoc signature to just get it working on one device.

You must apply the ad-hoc signature before attempting to run the app. It seems macOS remembers if an app is not valid and will permanently refuse to run it if any kind of error occurs. So run the command below before even trying to run the app. If you tried to run the app already, try renaming the app, which seems to reset the state that macOS remembered.

Open a terminal to the folder with your exported app (extracted from the zip) and run the following command to apply an ad-hoc signature:

codesign --force --deep -s - myexport.app

Now the app has a signature that will work for your device only. The next step should now work.

Bypass security check (all devices)

There are two ways to bypass macOS's security checks that by default prevent you running an unrecognized app.

  1. Hold control and click the app in Finder, and select Open from the menu. You may need to do this twice.
  2. After attempting to run the app and seeing a 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.

Conclusion

Using NW.js you can publish desktop apps for the three major desktop platforms with integrated features like disk access and fullscreen display. However remember that users should run dxwebsetup.exe on Windows, and that you should extract the exported zip on the system you want to run the app on.

  • 7 Comments

  • Order by
Want to leave a comment? Login or Register an account!
  • How do you actually get the game to run on linux? There's a file with the game's name, but no extension!

    • Most Linux executables are not give a file extension. However, they have their permissions set so that the file is executable.

    • [-] [+]
    • 2
    • lpf's avatar
    • lpf
    • 2 points
    • (0 children)

    Hi there!

    I don't know if this is the wrong place to write this,

    I'm having troubles in exporting my game in nw.js format, while loading the NW.js versions, I'm being told that my internet connection is not working, which is not the case.

    Could you maybe help me with that?

  • When you've exported a game vie nw.js, how do you actually run it?

  • I was having problems running my NW exported game when running on Linux. It would silently fail to when trying to run from the file manager GUI. When I ran from the command line it showed a failure to find the shared library. I'm new to Linux so didn't pay much attention to the directory permissions, but then found that my game would run if I ran it with "sudo". I then saw that the subdirectories (lib and locales) had here permissions set to "drwxr r ". Changing these by performing chmod 755 on them added execute permissions (drwxr xr x) on for all users, and I could run my main executable without using "sudo".

  • For anywone looking to create a Windows Setup file that includes a direct X comment, there's a great tutorial here. (Be sure to look at the comment section for how to add the directx instilation section)

    construct.net/en/tutorials/creating-setup-file-nwjs-game-1376

  • Load more comments (1 replies)