This addon enables the development of Desktop apps with Ember, Ember Cli, and GitHub's Electron. It enables live development with Electron (similar to ember serve
) as well as testing in Electron (similar to ember test
and ember test --server
). It also comes with an integrated packager, turning your Ember App into standalone binaries for Windows, Mac OS X, and Linux. It also integrates the famous Ember Inspector. The commands are:
ember electron
- Run app in Electron with live-reload serverember electron:test
- Test the app using Electronember electron:test --server
- Test with Electron in development server modeember electron:package
- Create binaries (.app, .exe, etc) for your app
Ember-Electron builds on prior work done by @brzpegasus (author of ember-cli-nwjs
) and @joostdevries (author of ember-cli-remote-inspector
).
To see a real world example, check out Ghost Desktop.
⚠️ This addon needs at least Node 6.
To install the addon, run:
ember install ember-electron
Or, to install with npm - but please ensure (:warning:) that the blueprint generation runs - it creates necessary files and configuration for this addon to work. Please ensure that your tests
folder contains a package.json
and a electron.js
- and that locationType
in config/environment.js
is set to hash
.
npm install ember-electron
ember g ember-electron
Once you installed the addon, you'll notice that a new file called electron.js
was created in the root folder of your application. This is the entry point for Electron and is responsible for creating browser windows and other interactions with Electron APIs.
To run your app together with a file watcher in development mode (similar to ember serve
), you can run ember electron
. However, you will need to change your configuration for Ember and Electron to work well together: Electron does not support the History API. Therefore Ember-Cli must be configured to use the hash
location type. Update your config/environment.js
's locationType
config option to hash
. If you would like to support running the app both within and outside of Electron you can use the following switch:
locationType: process.env.EMBER_CLI_ELECTRON ? 'hash' : 'auto',
If you're running a later version of Electron, you will notice that ember-electron installs ember-inspector directly into Electron. Simply open up the developer tools and choose the Ember-tab, just like you would in Chrome.
In addition, Whenever you run ember electron
, the console output will give you a URL where Ember Inspector is live. Communication between your app in Electron and the Ember Inspector happens over WebSockets. By default, the console output should look like this:
--------------------------------------------------------------------
Ember Inspector running on http://localhost:30820
Open the inspector URL in a browser to debug the app!
--------------------------------------------------------------------
Starting Electron...
--------------------------------------------------------------------
To test your app, run ember electron:test
. If you prefer the live-reload mode, run ember electron:test --server
. The usual parameters are supported:
--server
- Run tests in interactive mode (default: false)--protocol
- 'The protocol to use when running with --server (default: 'http')--host
- The host to use when running with --server (default: 'localhost')--port
- The port to use when running with --server (default: 7357)--module
- The name of a test module to run--filter
- A string to filter tests to run
Ember-Electron comes with an integrated packager to create binaries (.app, .exe etc), which can be run with ember electron:package
. By default, the packager creates binaries for all platforms and architectures using your app's name and version as defined in package.json
. Under the hood, it uses the popular electron-packager module.
To create standalone binaries of your Ember App, simply run the following command.
ember electron:package
By default, ember-electron will package your whole dist
folder and all production dependencies as defined in package.json
. In addition, to ensure that Electron can start properly, it also includes electron.js
and package.json
. To configure which files make it into the package, use the copy-files
property the ember-electron section in your package.json
. Globs are accepted!
"ember-electron": {
"copy-files": [
"package.json",
"electron.js"
"main/*"
],
}
You can pass options to the packager by either putting configuration into your app's package.json
, or by passing a command line parameter to the ember electron:package
command. You can extend your existing package.json
with all available configuration options by running ember generate ember-electron
. In the case that an option is defined both on the command line and in the package.json, the command line option will be used.
-
--app-copyright
- String The human-readable copyright line for the app. Maps to the LegalCopyright metadata property on Windows, and NSHumanReadableCopyright on OS X. -
--app-version
- String The release version of the application. Maps to theProductVersion
metadata property on Windows, andCFBundleShortVersionString
on OS X. -
--arch
- String Allowed values: ia32, x64, all -
--asar
- Boolean Whether to package the application's source code into an archive, using Electron's archive format. Reasons why you may want to enable this feature are described in an application packaging tutorial in Electron's documentation. Defaults tofalse
.ordering
- String: A path to an ordering file for packing files. An explanation can be found on the Atom issue tracker.unpack
- String: A glob expression, when specified, unpacks the file with matching names to theapp.asar.unpacked
directory.unpackDir
- String: Unpacks the dir to theapp.asar.unpacked
directory whose names exactly or pattern match this string. Theasar.unpackDir
is relative todir
.
For example,
asar-unpack-dir=sub_dir
will unpack the directory/<dir>/sub_dir
. -
--build-version
- String The build version of the application. Maps to theFileVersion
metadata property on Windows, andCFBundleVersion
on OS X. -
--copy-dev-modules
- Boolean Copy dependency node modules from local dev node_modules instead of installing them. -
--defer-symlinks
- Boolean Whether symlinks should be dereferenced during copying (defaults to true) -
--download
- Object If present, passes custom options toelectron-download
(see the link for more detailed option descriptions and the defaults).cache
String: The directory where prebuilt, pre-packaged Electron downloads are cached.mirror
String: The URL to override the default Electron download location.strictSSL
Boolean: Whether SSL certificates are required to be valid when downloading Electron.
-
--dir
- String The source directory -
--icon
- String Currently you must look for conversion tools in order to supply an icon in the format required by the platform. If the file extension is omitted, it is auto-completed to the correct extension based on the platform.- OS X:
.icns
- Windows:
.ico
(See below for details on non-Windows platforms) - Linux: this option is not required, as the dock/window list icon is set via the icon option in the BrowserWindow contructor. Setting the icon in the file manager is not currently supported.
- OS X:
-
--ignore
- RegExp A pattern which specifies which files to ignore when copying files to create the package(s). Take note that Ember Electron creates a temp folder containingelectron.js
,package.json
, and Ember Cli'sdist
output folder. Glob patterns will not work. -
--name
- String The application name. -
--out
- String The directory where electron builds are saved. Defaults toelectron-builds/
. -
--overwrite
- Boolean Whether to replace an already existing output directory for a given platform (true
) or skip recreating it (false
). Defaults tofalse
. -
--platform
- String Allowed values: linux, win32, darwin, mas, all -
--prune
- Boolean Runsnpm prune --production
before starting to package the app. -
--version
- String Electron version (without the 'v') - for example,0.33.9
, see Electron releases for valid versions
-
--app-bundle-id
- String The bundle identifier to use in the application's plist -
--app-category-type
- String The application category type, as shown in the Finder via View -> Arrange by Application Category when viewing the Applications directory. For example,app-category-type=public.app-category.developer-tools
will set the application category to Developer Tools. Valid values are listed in Apple's documentation. -
--extend-info
- String Filename of a plist file; the contents are added to the app's plist. Entries inextend-info
override entries in the base plist file supplied by electron-prebuilt, but are overridden by other explicit arguments such asapp-version
orapp-bundle-id
. -
--extra-resource
- String Filename of a file to be copied directly into the app's Contents/Resources directory. -
--helper-bundle-id
- String The bundle identifier to use in the application helper's plist. -
--osx-sign
- Object If present, signs OS X target apps when the host platform is OS X and XCode is installed. When the value is true, pass default configuration to the signing module. The configuration values listed below can be customized when the value is an Object. See electron-osx-sign for more detailed option descriptions and the defaults.identity
- String: The identity used when signing the package via codesign.entitlements
- String: The path to the 'parent' entitlements.entitlements-inherit
- String: The path to the 'child' entitlements.
-
--protocol
- Array of strings The URL protocol scheme(s) to associate the app with. For example, specifyingmyapp
would cause URLs such asmyapp://path
to be opened with the app. Maps to theCFBundleURLSchemes
metadata property. This option requires a correspondingprotocol-name
option to be specified. -
--protocol-name
- Strings The descriptive name of the URL protocol scheme(s) specified via theprotocol
option. Maps to theCFBundleURLName
metadata property.
-
--win32metadata
- Object Object hash of application metadata to embed into the executable (Windows only):CompanyName
- StringLegalCopyright
- StringFileDescription
- StringOriginalFilename
- StringProductName
- StringInternalName
- String
You can test your application using Electron with the ember electron:test
command. However, because Chromium requires a display to work, you will need to create a fake display during your test in a headless environment like Travis CI or Circle CI. This addon automatically configures .travis.yml
, but if you'd like to configure it manually, ensure that you take the following steps:
- Install
xvfb
. It's a virtual framebuffer, implementing the X11 display server protocol - it performs all graphical operations in memory without showing any screen output, which is exactly what we need. A Jenkins addon is available. - Create a virtual
xvfb
screen and export an environment variable calledDISPLAY
that points to it. Electron will automatically pick it up. - Install a recent C++ compiler (e.g. gcc). This is to enable the CI server to build native modules for Node.js.
- Finally, ensure that
npm test
actually callsember electron:test
. You can configure what commandnpm test executes
by changing it in yourpackage.json
.
On Travis, the configuration should look like this:
env:
- CXX=g++-4.8
addons:
apt:
sources:
- ubuntu-toolchain-r-test
packages:
- xvfb
- g++-4.8
before_install:
- "npm config set spin false"
install:
- npm install -g bower
- npm install
- bower install
- export DISPLAY=':99.0'
- Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
Both Ember Cli and Node.js use require()
. Without ember-electron, Ember will start and overwrite Node's require()
method, meaning that you're stuck without crucial tools such as require('electron')
.
When using ember-electron, this conflict is automatically managed for you - you can continue to use Ember's require()
for Ember Cli modules, but also use requireNode()
for Node modules. The same is true for window.module
(which is available as window.moduleNode
) and window.process
(which is available as window.processNode
).
In addition, the require()
method is overwritten to resolve both AMD and Node modules (see below) - however, to maintain code sanity, I recommend using require()
and requireNode()
.
Ember-Electron does currently not create installers for you, but plenty of modules exist to automate this task. For Windows installers, GitHub's very own grunt-electron-installer does a great job. On OS X, you probably want to create a pretty DMG image - node-appdmg is a great command line tool to create images. If you'd like to follow GitHub's lead and stick with Grunt, consider grunt-appdmg
MIT - (C) Copyright 2015 Felix Rieseberg. Please see LICENSE
for details. Huge thanks to @brzpegasus (author of ember-cli-nwjs
) and @joostdevries (author of ember-cli-remote-inspector
) - their projects made the development of this project a lot easier.