SkelEktron
An unofficial Electron Application template.
SkelEktron was born to be a scratchpad application. A kitchen sink forked from the Quick Start app, where I could test code and ideas for another existing Electron project without messing the original source code. It eventually took its own road as a template application, a blueprint that provides common features and lets you concentrate on your application's specific code.
Core Features
- A smart cross-platform logger
- A ready-to-go auto updater
- Built-in support for Electron Builder
- Built-in support for different build targets (ie. release, debug, test, etc) with different settings
- A printer management feature (optional, fully supported on 64bit Mac/Linux)
Logger
SkelEktron's logger is a simple console.*
redirector. During development all the output is written to the terminal. When the application is packaged the output is redirected to a file:
- OSX applications log to
~/Library/Logs/YourAppNameWithoutSpaces.log
- Windows applications log to
C:\Users\[UserName]\AppData\Local\YourAppNameWithoutSpaces.log
(it also works when the app is packaged but not yet installed) - Linux applications log to
~/.YourAppNameWithoutSpaces.log
In other operating systems the output is still redirected to STDOUT
or STDERR
, but it can be easily modified in lib/log.js
.
The logger also adds the console.debug()
method, which is silenced when the application is built in "release" mode (the default).
Note: the log file is truncated each time the application starts. If you need to keep the log files, you have to modify the related write stream to use an a
or a+
flags.
Tip: on Windows PowerShell you can tail the log file with the command:
PS C:\src\skelektron> Get-Content -Path "C:\Users\[UserName]\AppData\Local\YourAppNameWithoutSpaces.log" -Wait
Auto Update
SkelEktron provides an ready-to-go auto update feature for Win and Mac applications, compatible with Electron Release Server. The application checks for updates at startup and downloads the package automatically. Once the update is downloaded, the user is prompted to update the application instantly or at the next restart.
To enable the updates, you just need to set up your server (see below) and configure the update URL into app/package.json
:
"config":
If the value is not set or is set to false
, the feature is disabled.
Printers management
With the printer module the application has access to the printers list and can send data directly to the chosen printer. The current implementation prints test pages in PDF or TXT format. For your specific implementations you can have a look at the examples.
Please Note: since very few apps would need printing ability, and it's not fully supported in Windows, printer management has been disabled by default. To enable the library:
- add the printer in
app/package.json
, - uncomment and customize
require('./lib/printer')
inmain.js
, - add and customize
require('./assets/js/printers.js')
to your HTML views.
Electron Builder support
SkelEktron comes pre-packaged and configured for Electron Builder with a two package.json
files structure. Build settings can be customized in development package.json
, you can find more details in the wiki.
Targeted builds
Sometimes you need to build different versions of your application, for example for releasing it to the public, for testing, for QA, etc. And each of these targets could require different settings (i.e. URL to load, debug enabled/disabled).
Each target is a JSON file stored in build/targets
, so you can have as many targets you need. The content of the selected file is merged with the config
object loaded from app/package.json
, allowing you to override default settings such as debug or update URL.
The default build target is "release", which builds a production version of the application with developer and debug tools disabled. You can build other targets by setting the BUILD_TARGET
env var.
$ BUILD_TARGET=debug npm run build:osx
Global settings
Once config is loaded from app/package.json
, the global.appSettings
variable is available to all backend modules, in frontend modules you can use require('remote').getGlobal('appSettings').someProperty
.
Other goodies
SkelEktron comes pre-packaged with other useful tools like pre-comit
, Devtron, and scripts for running tests and code coverage with Spectron, Mocha/Chai and Istanbul.
Be sure to check out the Electron API Demos for more goodies!
Build/Update Workflow
A suitable build flow can be:
- Version bump in
app/package.json
- Run
build
command for specific targets (dev/test/qa/release) platforms - Publish the packages
- create the remote release(s) for target and platform
- upload the assets
Build Notes
Although theoretically you can cross-build all platform versions of your app on a single operating system, I've found that building each release on the target OS, using VMs obviously, works best for me.
I use both node v4, v5 and v6.5.
For Windows builds I use an official Windows 10 development VM from Microsoft. You just need to install Python, Node and Git.
Sometimes I need a 32bit Windows 7 box, in those cases I use a basic VM with MS Visual C++ 2010 Redistributable Package (x86) (when I don't need compile power) or the full Visual Studio, along with Node, Python and Git.
Note: the author.name
field from app/package.json
is used by Squirrel as a path component for the shortcut menu icon, so double-check it for any special characters not allowed in Windows paths.
I often build .deb
packages from OS X, with fpm
and GraphicsMagick (brew install GraphicsMagick
) installed. Please check fpm repo for installation instructions.
Also Linux build may fail if GraphicsMagick does not find suitable sizes inside the app Icon. Required sizes are: 16x16x32, 32x32x32, 256x256x32, 512x512x32, 1024x1024x32.
For more detailed and updated information, you can check the official build instructions for Linux, OS X and Windows.
How To Customize The Installers
You can configure custom parameters for your platform installers inside the development package.json
of your project, for example (the osx icon parameter targets the mounted DMG icon):
"build":
See the builder options guide for the full reference.
How To Sign The Installers
In order to sign the installers you need to obtain 2 code-signing certificate in *.p12
format: one for Windows and one for OSX. The certificate must be accessible from the building machine via HTTPS (ie. GDrive, Dropbox).
Then on Windows PowerShell:
PS C:\src\skelektron> $env:CSC_LINK="https://url.to.my/certificate.p12"PS C:\src\skelektron> $env:CSC_KEY_PASSWORD="CertificatePassword"PS C:\src\skelektron> npm run build:win -- --sign
And from OSX Terminal:
$ export CSC_LINK="https://url.to.my/certificate.p12"$ export CSC_KEY_PASSWORD="CertificatePassword"$ npm run build:osx
Mac certificates are provided by Apple through XCode. To export a certificate in p12
format read this Apple doc.
How To Setup an Electron Release Server on Heroku with MySQL, Redis and S3
First checkout a copy of Electron Release Server and configure it to use MySQL, Redis and S3, then follow the instructions below.
Note: if you prefer, you can use mLab MongoDB for session storage and Heroku Postgres as main database.
-
Setup an S3 bucket where
- everyone can read (EveryOne: list)
- a custom
yourAppUser
, with specific credentials can write
-
Create an Heroku app (i.e.
your-electron.herokuapp.com
) using Heroku web UI or CLI tool -
Configure Heroku add-ons
- JawsDB for MySQL main database
- Heroku Redis for [session storage][salis-sessions]
-
Configure the environment vars for the app
- SITE_URL
- DATABASE_URL
- ADMIN_USERNAME
- ADMIN_PASSWORD
- S3_API_KEY
- S3_API_SECRET
- S3_BUCKET
- S3_REGION
- PORT
- REDIS_HOST
- REDIS_PASS
- REDIS_PORT
-
Import data into the app main database a tool of choice (Sequel for OSX, MySQL Workbench or other standard client)
-
Push the app to Heroku
git push heroku your-branch:master
-
Enjoy it!
Running the Tests
npm test
will run both unit and integration tests (Spectron). To run each test separately use npm run unit
and npm run integration
.
Contributing
See CONTRIBUTING file.
Credits
The Electron and Electron Builder team. Arek Sredzki for Electron Release Server, Ion for printer. Marco Piraccini and Bogdan Rotund. Kilian Valkhof for these UI pro tips.
Contributor Code of Conduct
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See CODE_OF_CONDUCT file.
License
SkelEktron is released under the MIT License. See the bundled LICENSE file for details.