DEV Community: Mitch Pierias

A Complete Electron Application Production Pipeline!

Mitch Pierias — Mon, 04 Feb 2019 03:51:00 +0000

I shared a blog post about configuring a complete electron application production pipeline, you can visit the medium post here if you'd like to read more.

Alternatively, a copy of the article is below. I've tried to reproduce styling as best I can within this Markdown editor, sorry for any inconsistencies

This article aims to outline a complete Electron development to rollout project pipeline. I’ll be covering everything from creating your initial Electron boilerplate with React, all the way through to building and publishing to an Amazon AWS S3 Bucket. We will then look at creating a static Gatsby site to list our distributions, delving into automatic S3 deployment and utilizing CloudFront and Route 53. The complete project for this can be found on Github.

Let’s get our project started by laying out our boilerplate, we’re going to make this easier by using create-reacton-app. Short disclaimer, I wrote it… so if your having problems, sorry! Okay back to work, install create-reactron-app globally and then execute with your PROJECT_NAME.

npm install -g create-reactron-app
create-reactron-app PROJECT_NAME
cd PROJECT_NAME

It’s that simple! Now you have a fully fledged Electron app with React boilerplate! You can run npm run start to open a development environment or npm run build && npm run dist to compile distribution binaries. It’s up to you what you’d like your app to do and look like from here. In the next section we will look at publish your distributions so their available to anyone!
Publishing Distributions

Let’s look at deploying out binaries for public access using an Amazon AWS S3. You’ll need to setup an Amazon AWS account before we start an hopefully have experience with the AWS services.

Getting your credentials

Login to your AWS account and access the IAM service, navigating into the users area. Select Add User and specify a name for the user who will access this projects deployment bucket, I named mine after my project agora-deploy. Tick Programmatic access and proceed to Set permissions. Here you want to search for ‘S3’ and select the S3-Manager permission. This will grant full access to S3 instances, primarily the read-write we need. Finally Add Tags, Review and Create user once you’ve configured any extras. Be sure to copy the access_key_id and access_secret_key displayed, we will need these later to configure the AWS-CLI. The permissions for your new user should now contain at least the following.

AWS Command Line Interface

Please follow the instructions on the following link to install and setup AWSCLI for your operating system.

Once you’ve got the command line tools setup, open the credentials file with nano ~/.aws/credentials and insert the keys we copied early when creating a new IAM user. I’ve named my configuration agora-deploy, this is useful if you have multiple projects with separate AWS access on your system.

[agora-deploy]
aws_access_key_id=JFRSHDKGYCNFPZMWUTBV
aws_secret_access_key=FK84mfPSdRtZgpDqWvb04fDen0fr3DZ87hTYEE1n

S3 Buckets

Now that you’ve setup your command line, navigate back to AWS console and create a new bucket to hold your distribution binaries. Just use the default settings when creating the bucket, then navigate through the Permissions and into the Bucket Policy.

Insert the following policy, granting public access to GetObject’s from the bucket. Be sure to insert YOUR_BUCKET_ARN followed by the top level directory your opening, I used /* here for all contents.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicReadGetObject",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "YOUR_BUCKET_ARN/*"
        }
    ]
}

And your set, the buckets now ready to serve your distribution. You could manually upload the build files, or continue onto the next section were we will look at automating distribution publishing.

Configuring Electron-Builder

We need to add some additional configuration to our Electron build properties for our new S3 instance. Add the following publish settings to your package.json.

"build": {
  ...
  "publish": [
    {
      "provider":"s3",
      "bucket":"YOUR_BUCKET_NAME"
    }
  ]
}

I also updated my scripts with the following two commands.

"scripts": {
  ...
  "dist": "electron-builder --publish never --linux --mac",
  "release": "npm run dist --publish always"
}

The dist script compiles binaries without publishing and the release script executes the dist script with while overwriting the --publish flag. If you’ve configured your AWS command line credentials and spelled everything correctly, you should be able to run npm run release to have electron-builder build and publish your distributions.

Content Delivery

Now that we have our application project setup, building and publishing, we can move onto creating our web interface to help user easily find the installer they need. The source code for this section can be found at the following GitHub repository.

Project Setup

I’m going to be building a static site to list the distributions. For this I’ll be using Gatsby and configuring automatic publishing to S3, and served from CloudFront. Let’s start by installing Gatsby’s command line interface tools, then run gatsby new followed by our application name to create our project boilerplate.

npm install -g gatsby-cli
gastby new APP_NAME

I’ll quickly add links to the binaries using the S3 Object URL within the index.js component. You can build your site out however you’d like here.

<Link to=”https://s3-ap-southeast-2.amazonaws.com/agora-distribution/Agora-0.2.3.dmg”>Mac</Link>
<Link to=” https://s3-ap-southeast-2.amazonaws.com/agora-distribution/Agora+0.2.3.AppImage”>Linux</Link>

Finally we can run npm run build to compile our static site, then move onto configuring our S3 and CloudFront environment to display it. The output of our build will be in the public folder, the contents of this folder is what we will move to our S3 Bucket.

Please be aware that some AWS services can take up to 24 hours to propagate changes across all edge locations, and be discoverable.

Before we can begin, you’ll need to have a domain name ready. We could do this with the resource URL’s generated for our instances, but there’s really no reason you’d ever need to do such a thing.

Configuring HTTPS

As a bonus to our users, we’re going to setup SSL so they can trust we really are who we say we are. Within the AWS console, navigate to the Certificate Manager and Request a certificate. Follow the prompts to setup, entering your domain or multiple domains, and selecting DNS Validation as the validation method.

Once your certificate has been requested, you’ll need to follow the instructions listed to complete issuance. It may take up too an hour for Route 53 and Certificate Manager to synchronize and issue the certificate.

S3 Hosting

We’re going to need an S3 bucket to hold all our static build files. Open S3 and create a new bucket, using your domain name as the bucket’s name. Next open the bucket settings navigate to Properties and configure your Static website hosting like so. We’re telling our bucket to act as a web server, returning the specified index document when no resource is specified and the error document when a resource isn’t found. We will set ours as the default files outputted from Gatsby’s build process. We don’t need to configure our bucket policy yet, we will have CloudFront do that later.

Setting up Cloudfront

We could configure our S3 Bucket to directly serve our content, but then we loose the advantage of SSL encryption and high speed delivery. Let’s setup a CloudFront instance instead to build an edge cache from our bucket contents and deliver it with SSL. Open the CloudFront Service within AWS, Create Distribution, and Get Started with a Web distribution. We have a little bit to configure here so stay patient.

Origin Settings
- Origin Domain Name: YOUR_S3_BUCKET_ARN
Default Cache Behavior Settings
- Viewer Protocol Policy: Redirect HTTP to HTTPS
Distribution Settings
- SSL Certificate: Custom SSL Certificate (Select the cert assigned earlier)
- Default Root Object: index.html

You can setup any additional configuration here you like, like custom headers. Next select Create Distribution and Amazon will start up the new instance. This will take some time, go have a coffee while the instance starts and propagates across all edge locations. We will need the service to be discoverable for the next section, configuring Route 53.

Domain Routing

So we’ve setup CloudFront to cache and serve our static site from S3, now we need to configure Route53 to provide a user friendly domain for our CloudFront instance. Navigate over to Route53, select the Hosted Zone associated with your domain, or create one if you haven’t already. Then Create Record Set, type A — IPv4 address, select Alias Yes and set the Alias Target as your CloudFront instance. Again, the CloudFront instance could take up too 24 hours to appear across other services. Once this is setup, you should be able to visit your domain after a few minutes and see your static site appear.

Automating S3 Deployment

We previous manually copied the entire contents of the build folder into our S3 bucket. There’s nothing technically wrong with this… but we’re all about automation and making things simpler! So let’s setup gatsby-plugin-s3 to deploy our build to S3 in just one command.

npm install -s gatsby-plugin-s3

Then we want to configure the plugin within our gatsby-config.js file. Add the following configuration object into the plugins array:

plugins: [
  ...
  {
    resolve: 'gatsby-plugin-s3',
    options: {
      bucketName: 'agora.pierias.com'
    }
  }
  ...
]

Finally we’re going to add a deploy command to the package.json like so:

"scripts": {
  ...
  "deploy": "gatsby-plugin-s3 deploy"
  ...
}

Before you can run this you’ll need to call npm run build to update the plugins in .cache, then you can run the npm run deploy command, following the prompts to deploy to S3. Remember to setup your ~/.aws/credentials with your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from the AWS IAM service. More details on the S3 plugin can be found here.

Thank you!

You should now have a full production pipeline setup. We could also add a GraphQL query to our Gatsby site in order to fetch the latest build resource URL from our deployment S3 Bucket. If you’d like to visit the live website deployed in this example, it can be found at Agora.

The Dream Team — React with Electron

Mitch Pierias — Tue, 18 Dec 2018 00:08:56 +0000

So you ‘re either a React developer dabbling into the world of electron, or your looking to extend the abilities of Electron. Either way, you’ve ended up here because you’ve asked yourself the same question that took me down the rabbit hole, “How can I use React inside Electron?”.

I’m not going to be making anything spectacular in this example. To be honest, I had trouble compiling my own Electron project with React, so I simplified everything down to this boilerplate template. In this example, we’re simply going to make React compile our basic project, then build our application distributions using Electron. The complete code for this example can be found here on GitHub.

Creating the Project

Before we can start building our electron application we first need to install a few dependencies and define our project structure. Firstly, create a new directory for your project and navigate inside, then run npm init and fill out the prompts to create your project boilerplate.

mkdir reactron && cd reactron
npm init

Now we’re ready to start installing our dependencies like React and React DOM! We’re also installing path as a production dependency cause we will be using it in with Electron later.

npm install --save react react-dom path

I’m not going to go over the React code, that could take a very long time depending on how far we choose to go. So I’m going to assume you know the basics. If not, you can just copy the files in the ./src directory from the GitHub repo and follow one of these tutorials if you’d like to learn more.

Webpack Setup

Now we need to compile our React project down into a single bundle, for this we will use Webpack.

npm install --save-dev webpack webpack-cli

We’re also going to need webpack loaders like babel, style loaders and html compilers, let’s install those and delve a little deeper into what they do.

npm install --save-dev babel-core@6 babel-loader@7 babel-preset-env@1 babel-preset-react@6

Babel is the loader responsible for parsing all our fancy new-age Javascript into the currently supported specification ES5.

babel-core: Transforms your ES6 code into ES5.
babel-loader: Webpack helper plugin to parse ES6 dependencies into ES5.
babel-preset-env: Determines which transformations/plugins to use and polyfills.
babel-preset-react: Presets for all React plugins.

npm install --save-dev css-loader style-loader html-webpack-plugin

style-loader: Compiles the referenced css files in our React components and injects them into the build file.
css-loader: Is the parser to help Webpack interpret and transform our CSS.
html-webpack-plugin: Outputs a compiled html file with resources adn tags linked.

There’s going to be allot of dependencies building up now… don’t worry, it’s just because of Webpacks extensability. Let’s define our project structure and start coding our resources, your project should resemble something like the following;

Reactron
|- assets
  ...react-assets...
|- build
  |- bundle.js
  |- index.html
|- dist
  ...electron-build-files...
|- node_modules
  ...installed-modules...
|- src
  |- index.js
  |- index.html
  |- index.css
|- package.json
|- main.js
|- webpack.config.js

Configuring Webpack

Now we’re ready to start configuring Webpack to bundle our React project and resources into our ./build directory for Electron. To start, open webpack.config.js and import the webpack, path and html-webpack-plugin modules.

const webpack = require('webpack');
const path = require('path');
const HtmlWebPackPlugin = require("html-webpack-plugin");

HTML-Webpack-Plugin

The html-webpack-plugin will take care of compiling our entry index.html file after webpack has done it's magic.

const htmlPlugin = new HtmlWebPackPlugin({
 title: "Reactron",
 template: "./src/index.html",
 filename: "./index.html"
});

Then we will configure our html-webpack-plugin. This will handle injecting resources and data into our ./src/index.html template through the Webpack build process, outputting the compiled result along with the bundled Javascript into the output directory.

The Webpack Build Pipeline

Now we are finally ready to configure our Webpack build pipline. Below everything we just wrote, define the following;

module.exports = {
 entry: './src/index.js',
 target: 'electron-renderer',
 output: {
  path: path.resolve(__dirname, 'build'),
  publicPath: './',
  filename: 'bundle.js'
 },
 module: {
  rules: [
   {
    test: /\.js$/,
    exclude: [
     /node_modules/,
     /.json?/
    ],
    use: {
     loader: 'babel-loader',
     query: {
      presets: ["env","react"]
     }
    }
   }, {
    test: /\.(s*)css$/,
    use: ['style-loader','css-loader']
   }
  ]
 },
 plugins:[
  htmlPlugin
 ],
 resolve: {
  extensions: ['.js','.jsx']
 }
}

I don’t want too delve deep into Webpack, but you can read the the official documentation and examples here if you’d like to explore it further. This code snippet is essentially telling Webpack where our entry file is, where we want to output, and using what modules and plugins.

Electron

We’ve now build our Electron renderer with React, bundled with Webpack, and now we’re ready to begin coding our Electron application to serve it all.

npm install --save-dev electron

Coding our Electron Application

Let’s open the ./main.js file and copy in the following;

const { app, BrowserWindow } = require('electron');
const path = require('path');

let mainWindow = null;

function createWindow() {

 mainWindow = new BrowserWindow({
  width:600,
  height:400
 });

 mainWindow.loadFile(path.resolve(__dirname,'build/index.html'));

 mainWindow.on('closed', () => {
  if (process.platform !== 'darwin') app.quit();
 });
}

app.on('ready', createWindow);

This is the absolute minimum code to start an Electron application. We’re importing our modules path and the app and BrowserWindow components from electron, then defining an empty mainWindow reference and createWindow() function before attaching it to the app.on(‘ready’) event. Our createWindow function is initializing a new BrowserWindow, loading the ./build/index.html file we compiled with Webpack earlier, and handling the mainWindow.on(‘closed’) event.
Running the App

And that’s it! We can execute npm webpack --mode production to compile and then npm electron . to start our Electron application. Let’s complete our project by compiling everything into a distribution with electron-builder.

Electron Builder

npm install --save-dev electron-builder

The Build Property

The majority of our electron-builder configuration happens inside the build property within our package.json.

"build": {
  "productName":"Reactron",
  "appId":"com.reactron.app",
  "directories": {
    "buildResources":"build",
    "output":"dist"
  }
  ...
}

We’re defining our productName which is self explanatory and the appId which is typically a unique identifier like a URL on the web. The important property is the directories, here you’ll specify the buildResources where Electron will find your bundled Webpack output, and the output setting which defines the directory to output the build.

"directories": {
  ...
},
"files": [
  "**/*",
  "build/**/*",
  "node_modules/**/*"
]

Now we specify the files to scan and package into our application bundle and we’re ready to run!

node electron-builder