Easy to use, ready for distribution boilerplate for Electron Angular applications supporting native code.
Native code is supported in two different ways:
- native node.js addon (.node) using nan.
This is useful when you own the code and you want it to be part of the build.
In this case the native source code is part of your application code base and compiled with node-gyp. - Native library (.dll, .so or .dylib) using node-ffi-napi.
This is useful when you don't own the code of the native library or, alternatively, have another project which already compiles to a native library and you want to utilize this library in your Electron application.
In this case you supply precompiled libraries and use them via Foreign Function Interface (node-ffi-napi)
- Electron 5
- Spectron 7
- Angular 8
- Angular CLI 8
- Angular AoT for production
- Typescript 3.4
- Native node.js addons (using nan)
- Native libraries support (using node-ffi-napi)
- Hot reload for development
- CI configs for Windows (AppVeyor), Linux and Mac (Travis CI)
-
In order to clone and run this repository you'll need Git, Node.js and yarn installed on your computer.
- bash command line is required (use git-bash for windows)
-
Clone the repository
-
If you're behind a corporate firewall configure
git
proxy:git config --global http.proxy http://proxy.company.com:port git config --global https.proxy http://proxy.company.com:port
-
From your bash (git-bash or similar) command line:
# Clone this repository # git > 2.13 git clone --recurse-submodules https://github.com/just-jeb/electron-angular-native # git <= 2.12 git clone --recursive https://github.com/just-jeb/electron-angular-native # Go into the repository cd electron-angular-native
-
-
Prepare the environment
-
If you're behind a corporate firewall configure
yarn
proxy:yarn config set proxy http://proxy.company.com:port yarn config set https-proxy http://proxy.company.com:port
-
EXTREMELY IMPORTANT: Make sure you have
python v2.7
and appropriateC\C++ compiler toolchain
installed:You will also need to install:
-
On Unix:
python
(v2.7
recommended,v3.x.x
is not supported)make
- A proper C/C++ compiler toolchain, like GCC
-
On Mac OS X:
python
(v2.7
recommended,v3.x.x
is not supported) (already installed on Mac OS X)- Xcode
- You also need to install the
Command Line Tools
via Xcode. You can find this under the menuXcode -> Preferences -> Downloads
- This step will install
gcc
and the related toolchain containingmake
- You also need to install the
-
On Windows:
- Option 1: Install all the required tools and configurations using Microsoft's windows-build-tools using
npm install --global --production windows-build-tools
from an elevated PowerShell or CMD.exe (run as Administrator). - Option 2: Install tools and configuration manually:
-
Visual C++ Build Environment:
- Option 1: Install Visual C++ Build Tools using the Default Install option.
- Option 2: Install Visual Studio 2015 (or modify an existing installation) and select Common Tools for Visual C++ during setup. This also works with the free Community and Express for Desktop editions.
💡 [Windows Vista / 7 only] requires .NET Framework 4.5.1
-
Install Python 2.7 (
v3.x.x
is not supported), and runnpm config set python python2.7
(or see below for further instructions on specifying the proper Python version and path.) -
Launch cmd,
npm config set msvs_version 2015
-
If the above steps didn't work for you, please visit Microsoft's Node.js Guidelines for Windows for additional tips.
- Option 1: Install all the required tools and configurations using Microsoft's windows-build-tools using
If you have multiple Python versions installed, you can set
npm
's 'python' config key to the appropriate value:$ npm config set python /path/to/executable/python2.7
Note that OS X is just a flavour of Unix and so needs
python
,make
, and C/C++. An easy way to obtain these is to install XCode from Apple, and then use it to install the command line tools (under Preferences -> Downloads). -
-
From your bash (git-bash or similar) command line:
# Install dependencies yarn
-
- All the source code resides in
src/
directory - All the native source code resides in
src/native/
directory (a new native source code shall be put there as well) - Precompiled binaries (
simplelib
) are fetched from another git repository as git submodule and can be found innative-artifacts/precompiled-libraries
directory.
If you have any precompiled binaries you'd like to use in your project just put them inside this directory, while keeping platform and architecture subdirectories same to thesimplelib
. - Native artifacts that were compiled from the source code as part of the build can be found in
native-artifacts/native-addons
directory (first time compiled onyarn
)
You can define application name, version, author and runtime node dependencies in app.package.js
-
Running application in debug mode:
yarn start
This will run your Electron Angular application in watch mode, i.e. if you change any
.ts
file the application will reload the changes automatically.
The application starts with debug tools open so that you can place breakpoints and debug your Typescript code.Note that first time you run
yarn start
the application might open with console error saying "Not allowed to load local resource: file:///.../electron-angular-native/serve/index.html".
The reason for that is that webpack compilation and electron serve run simultaneously and the application starts before the code is ready.
All you need to do is wait - once the compilation is complete the application will reload with the compiled code. -
Debugging production build (AoT, Uglify etc.):
Sometimes you want to make sure your code compiles in production mode during the development (or even debug AoT related issues).
In order to build the application in production mode run:yarn build:prod
If you want to debug the application in production mode (built with AoT) use this:
yarn start:prod
-
Compiling native code:
Native code is not compiled on every
yarn start
(it's only compiled onyarn
and before the distribution), but if you want to recompile it, run the following command from your bash command line:yarn electron:build:native
-
Running end to end tests with Spectron:
To run end to end tests use the following command:
yarn e2e
This will run all the tests in
e2e
directory (the tests extension must be.e2e-spec.ts
).
For your convenience there is a helper classSpectronUtils
which can be used for tests definition and two test examples:native-links.e2e-spec.ts
verifies that the links that loaded from native modules present upon the application startsanity.e2e-spec.ts
verifies that the application starts
Note that end-to-end tests check the end user application (meaning the application created with
yarn dist
command). This means that prior to executingyarn e2e
you have to executeyarn dist
at least once
-
Run the following from the root folder to create a distribution for:
-
Current platform:
yarn dist
-
Windows 32 bit:
yarn dist:windows:32
-
Windows 64 bit:
yarn dist:windows:64
-
Linux 32 bit:
yarn dist:linux:32
-
Linux 64 bit:
yarn dist:linux:64
-
OSX:
yarn dist:osx
-
-
Be aware that cross-platform builds are performed on remote server
-
Distributed application is built in production mode (to benefit from Angular AoT).
If for some reason you want it in dev mode (JIT), runyarn dist:dev
-
Build artifact can be found in build-artifacts folder