Integration with an Electron app

Setapp Framework Node.js wrapper

1. Add @setapp/framework-wrapper to your project
2. Set an app bundle ID
3. Add a public key to your app
4. Allow Setapp to update your app
5. Use Setapp Framework
6. Integration sample

Add @setapp/framework-wrapper to your project

1. Add our node package to your dependencies.

   package.json

   Diff

   {
     "dependencies": {
   +   "@setapp/framework-wrapper": "^3.1.2",
       ...
     },
   }

2. To rebuild the native module to the currently installed Electron version, you should have 24.1.1 electron-builder version developer dependency. Also, you will need to add the postinstall script hook.

   package.json

   Diff

   {
     "devDependencies": {
   +   "electron-builder": "^24.1.1",
   +   "@electron/notarize": "^1.2.1",
   +   "@electron/universal": "^1.3.4",
   +   "node-gyp": "^9.3.1",
       ...
     },
     ...
     "scripts": {
       "start": "electron .",
       "build": "electron-builder --mac",
   +   "postinstall": "electron-builder install-app-deps",
       ...
     },
     ...
   }

3. To build a univarsal binary with (arm64 & x86_64 architectures) - specify the --universal parameter for the electron-builder

   package.json

   Diff

   {
     ...
     "scripts": {
       "start": "electron .",
   -    "build": "electron-builder --mac",
   +    "build": "electron-builder --mac --universal",
       "postinstall": "electron-builder install-app-deps"
     },
     ...
   }

4. To avoid node-gyp errors when building an app on Apple Silicon CPU, add exceptions to the build.mac.files list:

   package.json

   Diff

   {
     "build": {
       "mac": {
         "files": {
   +      "!node_modules/@setapp/framework-wrapper/Setapp.xcframework/**/*.*",
   +      "!node_modules/@setapp/framework-wrapper/build/node_gyp_bins/python3",
   +      "!node_modules/@setapp/framework-wrapper/bin/**/*.node",
   +      "!node_modules/**/*.{mk,a,o,h,forge-meta}",
          ...
         }
       }
     }
   }

5. @setapp/framework-wrapper supports macOS Monterey (12.0) and higher, so you'll need to specify the minimum target version.

   package.json

   Diff

   {
     "build": {
       "mac": {
   +     "minimumSystemVersion": "12.0",
         ...
       }
     }
   }

Set an app bundle ID

Add -setapp suffix to your app identifier.

package.json

{
  "build": {
+   "appId": "com.setapp.fmwk.macos.TestApp-setapp",
    ...
  }
}

Add a public key to your app

1. Download Setapp Public key (a note on the right from the release info).
2. Put the downloaded setappPublicKey.pem file to the package resources folder.
3. Add downloaded resource to extraResources

   package.json

   Diff

   {
     "build": {
       "mac": {
         "extraResources": [
   +       {
   +         "from": "./res/setappPublicKey.pem",
   +         "to": "setappPublicKey.pem"
   +       }
         ...
         ],
       },
     }
   }

Allow Setapp to update your app

In macOS 13 (Ventura), Apple introduced a new Privacy Restrictions. Thus, to allow Setapp to update your app, you need to add the NSUpdateSecurityPolicy key to Info.plist of your resulting app. You can do it by adding the following lines to your package.json file:

package.json

{
  "build": {
    "mac": {
      "extendInfo": {
+       "NSUpdateSecurityPolicy": {
+         "AllowProcesses": {
+           "MEHY5QF425": [
+             "com.setapp.DesktopClient.SetappAgent"
+           ]
+         }
+       }
        ...
      },
    }
  }
}

Use Setapp Framework

Use setapp package in your Electron app project:

main.js

...
const { SetappManager, SETAPP_USAGE_EVENT, SETAPP_LOG_LEVEL } = require('@setapp/framework-wrapper');
...

We made Node.js wrapper API similar to the Setapp Framework macOS Swift API. For example, to present a release notes window in your app, you can use SetappManager.shared.showReleaseNotesWindow(). So you can easily refer to the macOS methods.

Integration sample

You can locate the Electron integration sample in the Samples/Electron folder of the Setapp Framework repository on GitHub.