2015-09-01 02:10:29 +00:00
# Application Distribution
2014-05-04 10:32:12 +00:00
2019-04-02 20:45:35 +00:00
To distribute your app with Electron, you need to package and rebrand it. The easiest way to do this is to use one of the following third party packaging tools:
* [electron-forge ](https://github.com/electron-userland/electron-forge )
* [electron-builder ](https://github.com/electron-userland/electron-builder )
2019-07-20 01:52:11 +00:00
* [electron-packager ](https://github.com/electron/electron-packager )
2019-04-02 20:45:35 +00:00
These tools will take care of all the steps you need to take to end up with a distributable Electron applications, such as packaging your application, rebranding the executable, setting the right icons and optionally creating installers.
## Manual distribution
2020-11-05 22:12:43 +00:00
2019-04-02 20:45:35 +00:00
You can also choose to manually get your app ready for distribution. The steps needed to do this are outlined below.
2016-11-25 23:36:34 +00:00
To distribute your app with Electron, you need to download Electron's [prebuilt
binaries](https://github.com/electron/electron/releases). Next, the folder
containing your app should be named `app` and placed in Electron's resources
directory as shown in the following examples. Note that the location of
Electron's prebuilt binaries is indicated with `electron/` in the examples
below.
2014-05-04 10:32:12 +00:00
2016-06-18 13:26:26 +00:00
On macOS:
2014-05-04 10:32:12 +00:00
2019-07-30 20:11:56 +00:00
```plaintext
2015-04-16 03:31:12 +00:00
electron/Electron.app/Contents/Resources/app/
2014-05-04 10:32:12 +00:00
├── package.json
├── main.js
└── index.html
```
On Windows and Linux:
2019-07-30 20:11:56 +00:00
```plaintext
2015-04-16 03:31:12 +00:00
electron/resources/app
2014-05-04 10:32:12 +00:00
├── package.json
├── main.js
└── index.html
```
2015-04-17 03:59:40 +00:00
Then execute `Electron.app` (or `electron` on Linux, `electron.exe` on Windows),
2015-09-01 02:10:29 +00:00
and Electron will start as your app. The `electron` directory will then be
your distribution to deliver to final users.
2014-05-04 10:32:12 +00:00
2015-09-01 02:10:29 +00:00
## Packaging Your App into a File
2014-12-29 18:46:15 +00:00
2015-09-01 02:10:29 +00:00
Apart from shipping your app by copying all of its source files, you can also
2016-05-06 17:09:24 +00:00
package your app into an [asar ](https://github.com/electron/asar ) archive to avoid
2014-12-29 18:46:15 +00:00
exposing your app's source code to users.
To use an `asar` archive to replace the `app` folder, you need to rename the
2015-04-16 03:31:12 +00:00
archive to `app.asar` , and put it under Electron's resources directory like
2015-10-14 10:28:27 +00:00
below, and Electron will then try to read the archive and start from it.
2014-12-29 18:46:15 +00:00
2016-06-18 13:26:26 +00:00
On macOS:
2014-12-29 18:46:15 +00:00
2019-07-30 20:11:56 +00:00
```plaintext
2015-04-16 03:31:12 +00:00
electron/Electron.app/Contents/Resources/
2014-12-29 18:46:15 +00:00
└── app.asar
```
On Windows and Linux:
2019-07-30 20:11:56 +00:00
```plaintext
2015-04-16 03:31:12 +00:00
electron/resources/
2014-12-29 18:46:15 +00:00
└── app.asar
```
2014-12-08 05:38:29 +00:00
2014-12-29 18:46:15 +00:00
More details can be found in [Application packaging ](application-packaging.md ).
2015-09-01 02:10:29 +00:00
## Rebranding with Downloaded Binaries
2014-12-29 18:46:15 +00:00
2015-04-16 03:31:12 +00:00
After bundling your app into Electron, you will want to rebrand Electron
2014-12-29 20:12:04 +00:00
before distributing it to users.
2014-09-29 13:34:54 +00:00
2014-12-29 20:12:04 +00:00
### Windows
2014-09-29 13:34:54 +00:00
2015-04-17 03:59:40 +00:00
You can rename `electron.exe` to any name you like, and edit its icon and other
2020-04-13 21:32:29 +00:00
information with tools like [rcedit ](https://github.com/electron/rcedit ).
2014-12-29 20:12:04 +00:00
2016-06-18 13:26:26 +00:00
### macOS
2014-12-29 18:46:15 +00:00
2015-04-17 03:59:40 +00:00
You can rename `Electron.app` to any name you want, and you also have to rename
2016-09-01 14:49:36 +00:00
the `CFBundleDisplayName` , `CFBundleIdentifier` and `CFBundleName` fields in the
2015-04-17 03:59:40 +00:00
following files:
2014-12-29 18:46:15 +00:00
2015-04-16 03:31:12 +00:00
* `Electron.app/Contents/Info.plist`
2015-04-17 03:59:40 +00:00
* `Electron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plist`
You can also rename the helper app to avoid showing `Electron Helper` in the
Activity Monitor, but make sure you have renamed the helper app's executable
file's name.
The structure of a renamed app would be like:
2019-07-30 20:11:56 +00:00
```plaintext
2015-04-17 03:59:40 +00:00
MyApp.app/Contents
├── Info.plist
├── MacOS/
│ └── MyApp
└── Frameworks/
└── MyApp Helper.app
├── Info.plist
└── MacOS/
└── MyApp Helper
```
2014-12-29 18:46:15 +00:00
2014-12-29 20:12:04 +00:00
### Linux
2014-12-29 18:46:15 +00:00
2015-04-17 03:59:40 +00:00
You can rename the `electron` executable to any name you like.
2014-12-29 20:12:04 +00:00
2015-09-01 02:10:29 +00:00
## Rebranding by Rebuilding Electron from Source
2014-12-29 20:12:04 +00:00
2015-04-17 03:59:40 +00:00
It is also possible to rebrand Electron by changing the product name and
2018-09-09 01:15:32 +00:00
building it from source. To do this you need to set the build argument
corresponding to the product name (`electron_product_name = "YourProductName"`)
in the `args.gn` file and rebuild.
2014-12-29 20:12:04 +00:00
2016-05-27 21:00:04 +00:00
### Creating a Custom Electron Fork
Creating a custom fork of Electron is almost certainly not something you will
need to do in order to build your app, even for "Production Level" applications.
2017-06-26 05:14:24 +00:00
Using a tool such as `electron-packager` or `electron-forge` will allow you to
2016-05-27 21:00:04 +00:00
"Rebrand" Electron without having to do these steps.
You need to fork Electron when you have custom C++ code that you have patched
directly into Electron, that either cannot be upstreamed, or has been rejected
from the official version. As maintainers of Electron, we very much would like
to make your scenario work, so please try as hard as you can to get your changes
into the official version of Electron, it will be much much easier on you, and
2016-05-27 21:01:38 +00:00
we appreciate your help.
2016-05-27 21:00:04 +00:00
2016-05-27 21:02:22 +00:00
#### Creating a Custom Release with surf-build
2016-05-27 21:00:04 +00:00
1. Install [Surf ](https://github.com/surf-build/surf ), via npm:
`npm install -g surf-build@latest`
2016-05-27 21:01:38 +00:00
2. Create a new S3 bucket and create the following empty directory structure:
2016-05-27 21:00:04 +00:00
2017-11-20 06:18:24 +00:00
```sh
2018-07-20 17:58:19 +00:00
- electron/
2016-12-10 16:14:10 +00:00
- symbols/
- dist/
```
2016-05-27 21:00:04 +00:00
2016-05-27 21:01:38 +00:00
3. Set the following Environment Variables:
2016-05-27 21:00:04 +00:00
2020-11-05 22:12:43 +00:00
* `ELECTRON_GITHUB_TOKEN` - a token that can create releases on GitHub
* `ELECTRON_S3_ACCESS_KEY` , `ELECTRON_S3_BUCKET` , `ELECTRON_S3_SECRET_KEY` -
the place where you'll upload Node.js headers as well as symbols
* `ELECTRON_RELEASE` - Set to `true` and the upload part will run, leave unset
and `surf-build` will do CI-type checks, appropriate to run for every
pull request.
* `CI` - Set to `true` or else it will fail
* `GITHUB_TOKEN` - set it to the same as `ELECTRON_GITHUB_TOKEN`
* `SURF_TEMP` - set to `C:\Temp` on Windows to prevent path too long issues
* `TARGET_ARCH` - set to `ia32` or `x64`
2016-05-27 21:00:04 +00:00
2016-05-27 21:06:40 +00:00
4. In `script/upload.py` , you _must_ set `ELECTRON_REPO` to your fork (`MYORG/electron`),
2016-05-27 21:00:04 +00:00
especially if you are a contributor to Electron proper.
2016-05-27 21:01:38 +00:00
5. `surf-build -r https://github.com/MYORG/electron -s YOUR_COMMIT -n 'surf-PLATFORM-ARCH'`
2016-05-27 21:00:04 +00:00
2016-05-27 21:01:38 +00:00
6. Wait a very, very long time for the build to complete.