Embler

Turn binaries into applications.

Embler can be used with pkg to turn a Node.js project into an app, without having to resort to Electron. Useful for making a web interface, or a basic menubar app.

Supports macOS app, dmg, zip and tar.gz. dmg requires macOS

Installation

npm install embler

Usage

1. Specify options in your package.json like so:

   {
       "name": "affinity-photo",
       "author": "Serif",
       "version": "1.7.0",
       "scripts": {
           "build": "embler",
       },
       "embler": {
           "realName": "Affinity Photo",
           "appId": "com.seriflabs.affinityphoto",
           "mac": {
               "binary": "dist/affinity-photo-mac-bin",
               "icon": "icon.png",
               "formats": ["app", "dmg", "zip", "tar.gz"],
           }
       }
   }

2. Run npm run build

Usage with pkg

1. Run npm install pkg
2. Configure pkg and embler to your liking (Usage example above)
3. Set the scripts.build, bin and embler.mac.binary properties in your package.json like so:

{
    "bin": "index.js",
    "scripts": {
        "build": "pkg . --target macos --output dist/test-bin-macos && embler"
    },
    "embler": {
        "mac": {
            "binary": "dist/test-bin-macos"
        }
    }
}

3. Run npm run build
4. index.js is now an app.

API Usage

Supply options via json file:

const embler = require('embler')
await embler.build('embler.json')

Supply options directly:

const embler = require('embler')
await embler.build({
    name: "my-app",
    author: "kasper.space",
    version: "2.4.1",
    embler: {
        realName: "My App",
        // ...
    }
})

Options

name

• Required unless embler.name is specified
• The app's name. For example used for the app's process name
• Recommended to not use spaces or non-basic special characters

author

• Required unless embler.author is specified
• The app's author

version

• Required unless embler.version is specified
• The version of the app

embler.realName = "${name}"

• Recommended
• The app's name. This is the name users will see
• Spaces and special characters are allowed in this one

embler.appId = "com.example.${name}"

• Recommended
• The application id

embler.copyright = "Copyright © year ${author}"

• Human-readable copyright line

embler.outputDir = "dist"

• The output folder

embler.backgroundApp = false

• Whether the app will just run in the background app. On macOS, it won't show up in the Dock

embler.name

• Overrides name

embler.author

• Overrides author

embler.version

• Overrides version

embler.mac

• Object which contains macOS-specific options

embler.mac.binary

• Required
• Path to the binary which will run when the app is opened

embler.mac.category

• Recommended
• The app's category. Shown in /Applications in Finder when View > Use Groups is enabled using View > Sort By > Application Category
• Valid categories are listed in Apple's documentation

embler.mac.icon

• Recommended
• Path to your app's icon
• .icns or .png

embler.mac.formats = ["app"]

• Array of the formats Pakaer will output
• Supports app, dmg, zip and tar.gz. Creating dmg requires macOS

embler.mac.dmgBackground

• Path to a custom background image for the dmg
• The resolution should be 660x400
• To support retina displays, have an extra image at double resolution that ends with @2x. For example, you could have dmgbg.png and dmgbg@2x.png

embler.mac.darkModeSupport = true

• Turn this to false to disable dark mode support.

embler.mac.customInfo = {}

• In this object, you may add or overwrite Info.plist entries. Example:

  "customInfo": {
      "CFBundleDevelopmentRegion": "en"
  }

Dev Instructions

Get started

1. Install Node.js
2. Run npm install
3. Set up ESLint support for your code editor

To be able to run/test Embler:

4. Go to ./test (This is where you test Embler)
5. Run npm install
6. Run npm run compile (Compiles index.js to binary)

To test Embler:

cd ./test
npm run pack

Publish new version

1. Update CHANGELOG.md
2. Bump the version number, commit and tag:

   npm version <version>
   

3. Publish to npm:

   npm publish
   

4. Create GitHub release with release notes