Complete solution to build ready for distribution and "auto update" installers of your app for OS X, Windows and Linux.
- Native application dependencies compilation (only if two-package.json project structure used).
- Auto Update ready application packaging.
- Code Signing on a CI server or development machine.
- Build version management.
- Publishing artifacts to GitHub Releases.
electron-packager and appdmg are used under the hood.
Real project example — onshape-desktop-shell.
We strongly recommend to use two package.json files (it is not required, you can build project with any structure).
-
For development
In the root of the project. Here you declare dependencies for your development environment and build scripts.
-
For your application
In the
app
directory. Only this directory is distributed with real application.
Why the two package.json structure is ideal and how it solves a lot of issues (#39, #182, #230)?
- Native npm modules (those written in C, not JavaScript) need to be compiled, and here we have two different compilation targets for them. Those used in application need to be compiled against electron runtime, and all
devDependencies
need to be compiled against your locally installed node.js. Thanks to having two files this is trivial. - When you package the app for distribution there is no need to add up to size of the app with your
devDependencies
. Here those are always not included (because reside outside theapp
directory).
See options, but consider to follow simple guide outlined below at first.
-
Specify standard fields in the application
package.json
— name,description
,version
and author (for Linux homepage and license are also required). -
Specify build field in the development
package.json
:"build": { "app-bundle-id": "your.id", "app-category-type": "your.app.category.type", "win": { "iconUrl": "(windows-only) https link to icon" } }
See options. This object will be used as a source of electron-packager options. You can specify any other options here.
-
Create directory
build
in the root of the project and put yourbackground.png
(OS X DMG background),icon.icns
(OS X app icon) andicon.ico
(Windows app icon).Linux icon set will be generated automatically on the fly from the OS X
icns
file (or you can put them into thebuild/icons
directory — filename must contains size (e.g.32x32.png
)). -
Add scripts to the development
package.json
:"scripts": { "postinstall": "install-app-deps", "pack": "build", "dist": "build" }
And then you can run
npm run pack
ornpm run dist
(to package in a distributable format (e.g. dmg, windows installer, deb package)). Both scripts are the same because If script nameddist
or name has prefixdist:
, flag--dist
is implied.Please note — if you don't name your script
dist
or prefix it withdist:
and you don't pass--dist
flag, application will be not packed in a distributable format. -
Install required system packages.
Please note — packaged into an asar archive by default.
electron-builder
produces all required artifacts:
.dmg
: OS X installer, required for OS X user to initial install.-mac.zip
: required for Squirrel.Mac..exe
and-ia32.exe
: Windows installer, required for Windows user to initial install. Please note — your app must handle Squirrel.Windows events. See real example..full-nupkg
: required for Squirrel.Windows.-amd64.deb
and-i386.deb
: Linux Debian package. Please note — by default the most effective xz compression format used.
For auto updating to work, you must implement and configure Electron's autoUpdater
module (example).
You also need to deploy your releases to a server.
Consider using Nuts (GitHub as a backend to store assets) or Electron Release Server.
See the Publishing Artifacts section of the Wiki for information on configuring your CI environment for automatic deployment.
For windows consider only distributing 64-bit versions.
CFBundleVersion
(OS X) and FileVersion
(Windows) will be set automatically to version
.build_number
on CI server (Travis, AppVeyor and CircleCI supported).
Execute node_modules/.bin/build --help
to get actual CLI usage guide.
In most cases you should not explicitly pass flags, so, we don't want to promote it here (npm lifecycle is supported and script name is taken in account).
Want more — please file issue.
See node_modules/electron-builder/out/electron-builder.d.ts
. Typings is supported.
"use strict"
const builder = require("electron-builder")
// Promise is returned
builder.build({
platform: [builder.Platform.OSX],
"//": "platform, arch and other properties, see PackagerOptions in the node_modules/electron-builder/out/electron-builder.d.ts",
devMetadata: {
"//": "build and other properties, see https://goo.gl/5jVxoO"
}
})
.then(() => {
// handle result
})
.catch((error) => {
// handle error
})
See the Wiki for more documentation.