electron-angular-native

          

Linux/Mac: Windows:

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)

Features

• 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)

Getting ready

• 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 appropriate C\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 menu Xcode -> Preferences -> Downloads
        • This step will install gcc and the related toolchain containing make
    • 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.

          :bulb: [Windows Vista / 7 only] requires .NET Framework 4.5.1

        • Install Python 2.7 (v3.x.x is not supported), and run npm 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.

    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
    

Application structure

• 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 in native-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 the simplelib.
• 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 on yarn)

Application info

You can define application name, version, author and runtime node dependencies in app.package.js

Development

• 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 on yarn 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 class SpectronUtils 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 start
  • sanity.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 executing yarn e2e you have to execute yarn dist at least once

Distribution

• 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), run yarn dist:dev

• Build artifact can be found in build-artifacts folder

Useful links

• Electron documentation
• Using native modules in Electron
• Running binding.gyp in all subdirectories