meteor-electron

meteor-electron lets you easily transform your Meteor webapp to a desktop app. Its ultimate goal is to build meteor add-platform desktop.

Some of the things it does:

automatically builds and launches a desktop application, rebuilding when the native code changes
defines feature detection APIs and a bridge between web and native code
serves downloads of your application and update feeds

Getting Started

meteor add meson:electron

meteor-electron will download the Electron binary for your system and build and launch an Electron app pointing to your local development server. The download process may take a few minutes based on your Internet connection but only needs to be done once.

The app, as well as the ready-to-distribute binaries (see Deploy), is built within YOUR_PROJECT_DIRECTORY/.meteor-electron. This allows the apps to be easily located as well as the builds to be cached for speedier startup. You should add this directory to your .gitignore.

Configuration

Configuration is possible via Meteor.settings.electron. For example,

{
  "electron": {
    "name": "MyApp",
    "icon": {
      "darwin": "private/MyApp.icns",
      "linux": {
        "64x64": "private/icons/icon.png",
        "128x128": "private/icons/icon@2x.png",
        "256x256": "private/icons/icon@4x.png"
      },
      "win32": "private/MyApp.ico"
    },
    "version": "0.1.0",
    "description": "A really cool app.",
    "rootUrl": "https://myapp.com",
    "launchPath": "/app/landing",
    "downloadUrls": {
      "win32": "https://myapp.com/download/win/",
      "linux": {
        "deb": "/download/{{platform}}/{{version}}/{{name}}_{{version}}_{{arch}}.deb",
        "rpm": "/download/{{platform}}/{{version}}/{{name}}-{{version}}.{{arch}}.rpm"
      },
      "darwin": "https://myapp.com/download/osx/{{version}}/MyApp.zip"
    },
    "installer": {
      "linux": {
        "license": "MIT",
        "maintainer": "electron-webapps"
      }
    },
    "sign": "Developer ID Application: ...",
    "height": 768,
    "width": 1024,
    "frame": true,
    "title-bar-style": "hidden",
    "resizable": true,
    "protocols": [{
      "name": "MyApp",
      "schemes": ["myapp"]
    }],
    "appSrcDir": "private/app"
  }
}

icon: platform dependent icon paths relative to Meteor application root (not `appSrcDir`).; For Linux installers you can provide either a string with the path to the icon file or an object for multiple resultions as in the example (learn more here). For linux icons you can even provide absolute paths, as they are managed successfully.
version: must confirm to semver.
rootUrl: If unset, defaults to the `APP_ROOT_URL` and then `ROOT_URL` environment variables, in that order.
launchPath: If you want your app to open to a non-root URL. Will be appended to the root URL.
downloadUrls: URLs from which downloads are served. A CDN is recommended, but any HTTP server will do. You can place the installers inside the `public` folder of your Meteor app if you want Meteor to serve them.
downloadUrls.win32
: Copy the output of `grunt-electron-installer` (see Building and serving an auto-updating Windows app) to this location. Do not rename the files. If you wish to host the Windows installers at versioned URLs for caching or archival reasons, specify this as an object with the following keys.
downloadUrls.win32.releases: Copy the output of `grunt-electron-installer` (see Building and serving an auto-updating Windows app) to this location. Do not rename the files.
downloadUrls.win32.installer: If you like, you may copy the `Setup.exe` file created by `grunt-electron-installer` to this location rather than the "releases" location. If the URL contains '{{version}}', it will be replaced with `version`.
downloadUrls.darwin: Place the latest app at this location. If the URL contains '{{version}}', it will be replaced with `version`.
downloadUrls.linux: Place the latest app at this location. The URL may contain some variables to be dynamically replaced:; - `{{ext}}`: defaults to `["deb", "rpm", "AppImage"]`.; - `{{name}}`: defaults to sanitized (lowercased, hyphenated and deburred) `Meteor.settings.electron.name`, or `electron` if none provided.; - `{{platform}}`: defaults to the target platform of the build.; - `{{version}}`: defaults to `Meteor.settings.electron.version`.; `Meteor.settings.rootUrl` or `ROOT_URL`, defaulting in that order, is automatically prepended to the download URL(s) if it does not start with `http://` or `https://`.; This value can be of two types: string or object. There can exist multiple different Linux formats (`deb`, `rpm` or `AppImage` at this moment), so you can provide a generic URL pattern to build all the URLs (string) or you can provide an object with the format as key and the pattern as value. You can read more about this below.
sign: Must be set to enable auto-updates on Mac.
appSrcDir: A directory of code to use instead of meteor-electron's default application, relative to your app's project directory. See warning below.
installer: Use it to provide additional parameters to the installer builders.
installer.linux: Use it to provide additional parameters to the linux installer builders. You can learn about the extra parameters reading the docs of the involved NPM packages: electron-installer-debian for `.deb` packages, and electron-installer-redhat for `.rpm` packages.; When building `rpm` packages:; - The `license` parameter is required.; - `rpm` package is required when building from debian-based systems.; When building `deb` packages:; - The parameter `maintainer` is recommended to be provided.; - `fakeroot` package is required when building from debian-based systems.; Please, provide feedback to complete this section if you try to build linux installers from other linux systems (i.e., redhat-based) and/or platforms (Mac/Windows).
autoBuild: Prevent the Electorn app from automatically being built and launched when set to `false`.
autoPackage: Set to `true` to ZIP the Electron app for distribution.

Electron-specific code

By default, all client web code will be executed in Electron. To include/exclude code use Electron.isDesktop

if (!Electron.isDesktop()){
  showModal("Have you considered downloading our Electron app?");
}

Deploying

Hot code push will work to update your app's UI just like it does on the web, since the app is loading the UI from the web. If you want to update the part of the app that interfaces with the OS, though—to change the app icon, to add a menu bar icon, etc.—you'll need to distribute a new version of the .app or .exe. Here's how to do that.

Building and serving an auto-updating Mac app

Set Meteor.settings.electron.autoPackage to true to ZIP your app for distribution after it is built.
If you wish to enable remote updates, you will need to codesign your application. This requires that you build your app on a Mac with a Developer ID certificate installed. Set Meteor.settings.electron.sign to the name of that certificate.
Wait for the app to finish building and packaging, then copy YOUR_PROJECT_DIRECTORY/.meteor-electron/darwin-x64/final/YOUR_APP_NAME.zip to a publically-accessible location.
Set downloadUrls.darwin in Meteor.settings.electron to the URL of the location where you copied the ZIP.

Downloads of the Mac app will be served at your webapp's ROOT_URL + /app/download?platform=darwin.

Building and serving an auto-updating Windows app

Make sure that you have specified name, version, and description in Meteor.settings.electron.
Build the app on a Mac, because changing a Windows application icon does not work on Windows at present.
Ensure the URL specified by Meteor.settings.electron.downloadUrls.win32 has an empty RELEASES file.
On a Windows machine or in a Windows VM (not a Mac, at present), run the electron installer grunt plugin against your app. Your Gruntfile should look something like https://github.com/rissem/meteor-electron-test/tree/master/.test. The value of remoteReleases should be your webapp's ROOT_URL + '/app/latest'.
Copy the output to the server serving Meteor.settings.electron.downloadUrls.win32, to be served from that location.
When you publish a new update, run the installer again and it will generate diffs, a new RELEASES file, and new installers. After copying these to Meteor.settings.electron.downloadUrls.win32 again (overwriting the RELEASES file and installers), apps that check for updates should receive a new version.

Downloads of the Windows installer will be served at your webapp's ROOT_URL + /app/download?platform=win32.

Building and serving an auto-updating Linux app

Make sure that you have specified name, version, description, installer.linux.license and installer.linux.maintainer in Meteor.settings.electron.
Wait for the app to finish building and packaging, then copy YOUR_PROJECT_DIRECTORY/.meteor-electron/linux-x64/final/{installer} (where {installer} matches the name(s)/pattern(s) provided in Meteor.settings.electron.downloadUrls.linux) to a publically-accessible location.
Set downloadUrls.linux in Meteor.settings.electron to the URL(s) of the location(s) where you copied the installer(s).

Due to the different formats available for Linux, the download URLs will require an additional parameter format. Downloads of the Linux installers will be served at your webapp's ROOT_URL +:

/app/download?platform=linux&format=deb for the debian-based linux systems installer.
/app/download?platform=linux&format=rpm for the redhat-based linux systems installer.
/app/download?platform=linux&format=AppImage for the standalone distro-agnostic app executable.

Building for Windows on Mac

Install homebrew
brew update
brew install wine
Specify a Windows build in your settings (otherwise defaults to current platform (mac)).

{
  "electron": {
    "builds": [
      {"platform": "win32",
       "arch": "ia32"}
    ]
  }
}

Example

[TODO] Link to an awesome chat app

Q&A

Q: How is this different from all the other Meteor electron packages?

This package differs from Electrometeor and Electrify by not baking Meteor into the packaged app. This makes things significantly simpler, but if you need strong offline support, one of them is a better solution.

Q: How can I create new browser windows, set app notifications and all the other awesome native functionality that Electron gives me?

This project selectively exposes such functionality to the client, in a way that is safe and avoids memory leaks, via the Electron module--see client.js. To request that this module expose additional functionality, please submit a pull request or file an issue.

You may also substitute your own application code for meteor-electron's default application by setting the appSrcDir settings option. meteor-electron will continue to package your application and serve the application update feed and download URLs, but in-app functionality will be your responsibility. Warning: this responsibility includes setting up your application window and menu, checking for remote updates, registering the Electron module (that defines Electron.isDesktop), and possibly other things. If you take this route, it's recommended that you start by copying meteor-electron's app directory.

Also, you also probably want to keep your application code in a subdirectory of your application's private directory so that Meteor will observe changes to it and restart the server; when it does so, meteor-electron will rebuild and relaunch the app.

Q: How do I prevent the Electron app from being automatically built and launched?

Set Meteor.settings.electron.autoBuild to "false".

Q: How do I set the download URLs for Linux?

You can provide a global pattern to automatically generate URLs for all the supported formats (deb/rpm at this moment) like this:

{
  "electron": {
    ...
    "name": "Wonderful Meteor App",
    "version": "0.2.9",
    "rootUrl": "https://myapp.com",
    "builds": [
      {
        "platform": "linux",
        "arch": "x64",
        "formats": ["deb", "rpm", "AppImage"]
      }
    ],
    "downloadUrls": {
      "linux": "/download/{{version}}/{{platform}}/{{arch}}/{{name}}.{{ext}}",
    }
  }
}

which produces:

https://myapp.com/download/0.2.9/linux/x64/wonderful-meteor-app.deb
https://myapp.com/download/0.2.9/linux/x64/wonderful-meteor-app.rpm
https://myapp.com/download/0.2.9/linux/x64/wonderful-meteor-app.AppImage

If you do NOT provide the formats to be built in Meteor.settings.electron.builds for the Linux platform, then all the available and buildable formats will be built (all supported by your current distro which fulfill the required dependencies).

The other way you can set the download URLs is through an object:

{
  "electron": {
    ...
    "name": "Wonderful Meteor App",
    "version": "0.2.9",
    "rootUrl": "https://myapp.com",
    "downloadUrls": {
      "linux": {
        "deb": "/download/{{platform}}/{{version}}/{{name}}_{{version}}_x64.deb",
        "rpm": "/download/{{platform}}/{{version}}/redhat_{{name}}-{{version}}.x64.{{ext}}"
      }
    }
  }
}