Since its debut in 2013, React JS has been widely adopted as a technology favourite for web application development. JSX and by extension the virtual DOM have fundamentally shifted the way developers reason about building responsive interfaces. A 'batteries not included' philosophy has empowered front-end engineering teams to make the decisions about how to compose apps, however, there are architectural anti-patterns to be avoided when laying out a codebase. Applying simple principles will help build foundations that will last as technologies evolve.

Decoupled concerns  

React JS is popular, so too is Svelte, as is VueJS. What would happen if your team decided to pivot from one solution to another? Do you have a suitable separation of concerns that means you can refactor a portion of your app, or are you likely to find a wholesale rewrite is necessary?

Defining boundaries around the various concerns of your application will help isolate what needs to import React. Take for example interacting with an API surface, does this need to be achieved with a React import statement?  An adapter pattern can return data to React modules. The benefits are two fold:

1. Your API handler, and test files won't need to import React, or React Testing Library.
2. If you pivot away from React you can write a new adapter to communicate with the new view layer.

Monorepos

Despite numerous misconceptions about Monorepos, fundamentally they represent a means to co-locate logical packages inside the same repo, they allow teams to independently build constituent parts of a project without blocking colleagues. Stability challenges often occur in distributed teams where there is no robust process to ensure dependency management is understood by producers and consumers of those packages.

If a Monorepo is right for your problem space, identify the areas of concern up-front, use the single responsibility principle to help define what these are:

- package.json
- ...
|
---- /packages
    |
-------- /components
        |- package.json
        |- ...
-------- /routes
        |- package.json
        |- ...
-------- /api-handler
        |- package.json
        |- ...
-------- /api-react-adapter
        |- package.json
        |- ...

each package can run unit tests, perform linting, and create build artefacts etc, in isolation, which will speed up build times, and streamline developer workflows, this will also aid the first point ☝️ that your api-handler should not need to import React, and so your package.json file can omit this.

Technical scorecard

As a codebase grows and evolves, it will inevitably accrue technical debt, this can manifest for a range of reasons, some being:

• Applying DRY principles, that introduce abstractions, without being able to refactor all previous implementations.
• Discovering a preferred approach, such as using functional components over classes.
• Identifying new methods of testing, for example using MSW instead of mocking fetch.

Technical debt presents several challenges including:

• Onboarding new starters - where it requires context from mentors who must point to the preferred approach.
• Changing business logic, where it requires touching and refactoring 'outdated' patterns.

A technical scorecard can help to track this, and be a useful input when understanding pain points. In the right hands it can highlight priority. A good technical scorecard can measure other dimensions too, such as developer satisfaction, time spent fixing vs building, as well as general codebase health. This is a worthwhile endeavour if your codebase is sufficiently growing and you are ramping up development resource.

Further reading

• VIPER design patterns for IOS
• Presentation Model - Martin Fowler
• Adapter Pattern for Javascript
• Misconceptions about Monorepos
• Special thanks to ManyPixels for imagery

Stepping away from a Software Management role, where I'd divided my time between technical leadership and people management, to a fully remote engineering role, was always going to require a change in mindset. Through this journey I've learned a few strategies which may be useful for others on the same path.

Separate your work space

I took a month off between jobs to build a home shed-office (pronounced 'shoffice'). This was the single best investment I made in the transition, it won't be feasible for everyone, but whatever your environment, consider this a sacred space that needs to be treated with respect:

• Keeping the space tidy, and clutter free.
• Educate others in the household to respect this space, this is where you will conduct yourself in a professional manner.
• Have an 'off switch', it can be closing a door, or packing away of equipment, but make sure you know what that ritual is, and repeat it.

Invest in audio visual

Regardless of how your company is distributed, stand-ups, company all hands, and 1-2-1's will likely feature the medium of video calls. How you appear and sound becomes an extension of your professional demeanour:

• Consider face on cameras, with support for HD.
• Simple lighting rigs will brighten dim spaces and improve streamed picture quality.
• Headphones with built in microphones will offer superior audio fidelity.

Balance over burnout

If you are fortunate enough to find a pursuit in life that you are passionate about, and create a set of favourable conditions to work in, it's very easy to get the balance wrong. I've spent most of my professional career fighting to get a balance that was right for me and those I love.  

• The brain processes information sequentially, which is why context switching is so expensive. Plan in half day increments.
• The context switch must factor in breaks.
• Exercise is paramount to a healthy physical and mental relationship with work. Set yourself up for success, prepare your workout/gear in advance, then you only need execute on it, a context change lends itself to this.

Micro-interactions

Continuing the topic of mental health, even the most introvert among us need to socialise. The opportunities for this are reduced when we are not co-located, so seeking and creating these opportunities is important.

• Asking for help is one of the easiest ways to do this. Pair programming using collaboration tools bridges the gap.
• Daily standup in a remote environment will take longer, as it's not just about impediments and work in flight, it's an opportunity for people to share and connect.
• Creating features of your work week, such as workshops and lightening talks will also create conditions for people to share and discuss areas of expertise.  

Further reading

• Lighting: Lighting ring, Light bar
• Video: Front-facing HD camera
• Headphones: best wireless headphones
• Pair programming: Liveshare for VSCode

The objective of the Ghost CLI project is to make setting up and maintaining a Ghost site as straight forward as possible

Blue-Green Deployments

An alternative approach to updating Ghost would be to use 'Blue-Green' deployments, for a more in-depth description check out Martin fowler's article on the subject. In essence, you have a duplicate setup, Blue(e.g. Live) and Green(New Ghost version). Once updated Green is ready to deploy, you cut-over all traffic from Blue to Green. This has a number of advantages, most notably:

• Reduced/No downtime
• Increased confidence and testing in production like environment
• Ability to rollback easily

Performing Blue-Green with Amazon Lightsail

Amazon Lightsail offers a cheap and easy means to standup virtual servers with a simplified management interface. Although this article focuses on AWS, you could apply the same practice to Digital Ocean or other providers.  

The prerequisites for setup are: AWS account, AWS static IP, and DNS configured (Cloudflare). all of which will be covered.

A core tenant of Dev-Ops is to treat servers as 'Cattle, not Cats', which is to say, it should be simple to standup and terminate servers with minimal system administration. In the case of Ghost you may want to speed up Green environment configuration by putting the setup into source control, but that will create it's own overhead as major releases will likely change this process.  

Creating your Green instance

Let's imagine you have a live v1 ghost blog served from AWS. You now want to upgrade to v2. From the AWS management console select Instances > Create instance and select the ubuntu configuration as defined by the Ghost stack guide. This will take a few moments to startup. You should have instances as follows where blue is live and green is your new candidate:

You can now setup your new instance following the Ghost how to guide. This should mean you are running the latest version of Ghost. Once done, you will want to use the Ghost admin console > Labs export/import feature to move across your old posts and metadata to the new Green instance. Finally you may want to upload your new vX compliant theme into the Green Ghost instance. You can check that your theme meets the version requirements using the gscan tool. Please note: Once setup is complete, to have a true production environment you may need to re-run the ghost-setup command with your live blog domain name to ensure NGINX correctly maps HTTP requests on startup.

Setup a Static IP Address with Lightsail

In the Lightsail console navigate to Networking > Create Static IP here we you will be asked to specify your availability region and an identifiable name for the IP address. Please note static IP addresses are only retained as long as they are attached to a specific instance, essentially a 'use it or loose it' policy. So be sure to attach to your Blue instance at this point. The IP address console should now display like so:

Routing Traffic to between Blue-Green

The domain name for your Ghost blog will point to your Blue(live) setup. Cloudflare offer free SSL that allows you to specify the static IP address to route all traffic to, meaning you can attach the static IP you created to either instance. If things go wrong and you need to rollback a straightforward re-attachment of the static IP to your Blue instance will reset you to your previous version. The console will show which instance has the static IP, in this example Green is now live:

Blue Green Considerations

Blue Green deployments are not a silver bullet, they come with their own tradeoffs, depending on the size and complexity of a service the cost overheads may be harder to justify. In the case of this example you could think of this as a transient event, where ghost-v1-blue is decommissioned, or you could use more general naming and keep both running so you can quickly and confidently keep pace with new updates without risking any production downtime.

Further reading:

If you are interesting in learning more about Blue-Green deployments and Dev-Ops best practices here is some recommended reading:

• Accelerate: The Science of Lean Software and DevOps
• The DevOps Handbook
• BlueGreenDeployment - Martin Fowler

Clojure is a versatile programming language founded on dynamic principles. Its speed and coherence have made it a desireable candidate for microservice achitectures, however the learning curve is steep.

Setting up a Clojure project

Clojures power also brings complexity. There are a number of ways to configure Clojure projects, but one of the most popular is leiningen. This simple configuration tool enables fast project setup, so you can focus on building.

Example Clojure webserver

Clojure is an ideal language for web projects, suitable for API and application development. This example project provides a webserver boilerplate with support for app routing and HTML templating.

Once Leiningen is installed follow these steps to setup a webserver at http://localhost:3000

git clone git@github.com:philipbeel/example-clojure-webserver-jetty-compojure-hiccup.git

cd example-clojure-webserver-jetty-compojure-hiccup

lein run

Webserver setup using Ring Jetty adapter

Ring Jetty adapter allows integration of a configurable webserver into any Clojure project, it provides options for threading, port configuration, and basic req/response structures. It can be used as the basis for web based projects.

Routing requests with Compojure

Compojure provides a comprehensive routing library. The example project implements a two routes, for an index page and a 404 page, demonstrating how these can be abstracted into a /routing directory.

Expressive HTML templating via Hiccup

Hiccup offers an expressive way to write HTML markup. The API reference documents how the structure can be extended to create dynamic markup. The example project demonstrates how this can be used in conjunction with script and stylesheets to render comprehensive HTML documents.

Further reading

Clojure is an extremly robust language, whilst setup can be challenging there are a great number of libraries that make it extremely enjoyable to work with. If you are interested in finding out more about Clojure, here are some recommended links:

• A set of exercises for learning Clojure
• Brave Clojure

Typescript provides strict typing, empowering teams to build enterprise applications that scale. Whilst precompilers offer benefits to Javascript, they present interoperability challenges when performing coverage checks on precompiled code.

Typescript coverage reports

Coverage reports give insight into statements, functions, branches, and lines, but not necessarily quality. It stands to reason that if your application code is written in Typescript, then your tests should be too. Further to this, having coverage represented in Typescript as opposed to compiled Javascript is invaluable in the development workflow.

Typescript coverage example

This example project demonstrates how to generate a Typescript coverage report for unit tests written in Mocha and executed with NYC.

git clone git@github.com:philipbeel/example-typescript-nyc-mocha-coverage.git

The example project implements a boilerplate Typescript app for a crude calculator, with addition and subtraction files located in calculator/ts/src. The coverage report is executed from package.json:

cd example-typescript-nyc-mocha-coverage
npm install
npm run coverage

Coverage interoperability explained:

The command executes the following behaviour in order to generate the report:

1. The package.json specifies configuration options for NYC, the app .ts files are included and all test files, denoted by *.test.ts are excluded from the coverage report
2. The /test directory includes a mocha.opts file, this tell Mocha where to find the tests that need executing.
3. The unit tests are run, then the results are collected by NYC, which produces a coverage summary and a generated /coverage directory outlining the full detailed report.

==== Coverage summary =======
Statements   : 100% ( 10/10 )
Branches     : 100% ( 0/0 )
Functions    : 100% ( 6/6 )
Lines        : 100% ( 10/10 )
==============================

Further reading:

Typescript solves a very specific problem, however, it may not be right for every situation. If you are interested in learning more here are some resources:

• Demystifying Typescript
• Typescript by example
• Typescript Vs Javascript

The advent of Amazon Lightsail makes it even easier to spin up low cost EC2 instances, these can be pre-configured with a range of images such as NodeJS. CodeAgainTomorrow provides a tutorial to get setup with Ghost, ideal for a blog. Securing your instance with SSL is essential for a number of security and SEO reasons, configuring SSL can be hard, but it doesn't have to be.

Prerequisites

The following assumptions will be made:

• You have acquired an SSL certificate from a vendor
• You selected the Bitnami NodeJS image for your Lightsail instance
• You own a domain name and you have setup DNS to point to your instance
• You have setup your ghost blog

Generating a CSR

Bitnami's Apache2 configuration comes with a self signed certificate pre-installed, which means the bitnami.conf only requires light modification. In order to swap the self signed cert for a trusted one, first you will need to generate a Certificate Signing Request (CSR)

1. Navigate to the apache2 configuration

SSH into your Lightsail instance and navigate to the conf directory:

cd /opt/bitnami/apache2/conf

This directory will already be populated with the self signed server.key, sever.crt.

2. Create request

Next a CSR and key must be generated. To avoid confusion it's recommended to use the domain name for csr/key. Modify and run the following command:

openssl req -new -newkey rsa:2048 -nodes -keyout domain-name.key -out domain-name.csr

When prompted enter information about the company and domain. Please note: United Kingdom region must use the 'GB' country code.

3. Copy the CSR

A new CSR and key will be generated, open the CSR and copy the entire contents:

cat domain-name.csr

Verification

Paste the CSR into the SSL vendors control panel. The certificate issuer will need to verify the owner of the domain, there are generally 3 ways to do this:

• Provide an accessible domain email address.
• Create a unique DNS CNAME.
• Upload a unique public facing asset to the server.

Choose the appropriate method and follow the vendors instructions, it can take up to one hour to be verified.

Upload signing materials

Once the SSL vendor has verified that you own the domain a set of signing materials will be available to download. Depending on the vendor the format can vary:

• domain.crt
• domain.ca-bundle (dependent on vendor)

Either SCP these files into /opt/bitnami/apache2/conf or touch the files and copy paste the contents of the signing materials, for consistency it's recommended to use the domain when naming these files.

cd /opt/bitnami/apache2/conf
touch domain.crt
vim domain.crt

Make certs available

To start using the new signing materials the bitnami.conf needs updating, open the configuration for editing:

vim /opt/bitnami/apache2/conf/bitnami/bitnami.conf

Search for the following lines:

<VirtualHost _default_:443>
  DocumentRoot "/opt/bitnami/apache2/htdocs"
  SSLEngine on
  SSLCertificateFile "/opt/bitnami/apache2/conf/domain.crt"
  SSLCertificateKeyFile "/opt/bitnami/apache2/conf/domain.key"

• SSLCertificateFile: replace with the newly added domain.crt
• SSLCertificateKeyFile: replace with the domain.key that you generated in the initial CSR request

Additionally if a domain.ca-bundle was provided in the signing materials include this line for Apache2:

SSLCertificateChainFile "/opt/bitnami/apache2/conf/domain.ca-bundle"

Exclusive use of https

In order to make exclusive use of https:// on all incoming requests, include the RequestHeader directive into the above block:

RequestHeader set X-Forwarded-Proto "https"

Restart Apache

For the changes to take effect, Apache must be restarted:

sudo /opt/bitnami/ctlscript.sh restart apache

The CLI will notify you if there were any issues restarting Apache2, assuming everything is successful, test out the domain name on https:// and you should get the padlock confirming you are now serving your ghost blog over SSL.

Building enterprise level web UI's is challenging. Functional Reactive Programming (FRP) may hold the solution with the advent of 'Reactive Extensions for JavaScript' also known as RxJS.

What is reactive programming!?

André Staltz introduction to 'reactive programming' gives a great overview to the subject, I strongly recommend you read this first.

Functional Reactive programming is a paradigm that combines event driven programming with the benefits of functional programming. UI development is a perfect use case, as the majority of engagement comes from user interaction.

Streams and monads

Event streams are the cornerstone of RxJS, however in order to explain this we must first understand monads, which is no easy task. If you've ever used libraries like jQuery, the syntax may feel familiar:

$('#id').fadeOut('slow').fadeIn('fast')

The conceptual idea of chaining functions onto monads means you can write succinct, readable code. RxJS builds on this theme by broadcasting and subscribing to event streams, functions can be chained to these event streams to perform a range of actions.

RxJS in practice

Let's put these concepts into practice. Imagine you are given a requirement to build a PIN entry feature, that must apply the following business rules:

• Accept only numeric values from the keyboard.
• Take a maximum of 4 numeric values.
• Update the UI to display the user input values in order.
• Display a notification when all criteria has been met.

Lets look at how we might implement this in RxJS:

    Rx.Observable.fromEvent(document, 'keyup')
        .debounce(100)
        .map((data) => data.key)
        .filter((key) => !isNaN(Number(key)))
        .take(4)
        .do(input => document.getElementsByTagName('input')[this.inputCount++].value = input)
        .count()
        .last(x => document.getElementById('notification').style.display='block')
        .subscribe(this.inputCount = 0);

Checkout the full example on Github

Please note this requires an ES6 compatible browser

In just 9 lines a stream has been created, which fulfils all these requirements. Lets step through the code to take a closer look at what's happening:

    // Create observer on the keyup event
    Rx.Observable.fromEvent(document, 'keyup')
        // Wait 100ms between user keyup events 
        .debounce(100)
        // Strip the keyboard keys value from the data object
        .map((data) => data.key)
        // Filter out everything but number keys
        .filter((key) => !isNaN(Number(key)))
        // Only accept 4 numerical key values
        .take(4)
        // Push this value into the N input field on the DOM
        .do(input => document.getElementsByTagName('input')[this.inputCount++].value = input)
        // Count the number of numerical keypresses
        .count()
        // On the last numerical keypress display a notification to the user
        .last(x => document.getElementById('notification').style.display='block')
        // Finally subscribe to the key up event and start the input count at 0
        .subscribe(this.inputCount = 0);

Considerations and improvements

This example implementation is not perfect. The view interaction is tightly coupled, ideally this would be handled by a mediator or other actor. Taking this idea further we could include:

• An external API to validate the PIN value is correct
• Error handling if the PIN does not match the expected value
• Handling mouse and manual focus events.

Summary

RxJS has a steep learning curve, but With Netflix driving the profile of this emerging set of libraries I expect resources and documentation to improve.

Having used RxJS in conjunction with Typescript and ES6 I have been really impressed by it's versatility, that said it may not suit every use case. If you are working on enterprise level applications with larger teams 20+ RxJS is worth some investigation.

Further reading:

• RxJS documentation
• The introduction to Reactive Programming you've been missing
• Netflix JavaScript Talks - RxJS + Redux + React = Amazing

The full exampe RxJS code can be found on Github:
https://github.com/philipbeel/example-rxjs

Creating modular, testable code in your Javascript projects is imperative. Coverage enables developers to measure their unit tests. Istanbul is one such tool and plays nicely with gulp. It can be used to cover statements, branches and functions.

What coverage tools are:

Useful indicators for project health, when combined with CI pipelines they ensure new and modified code is suitably covered and less likely to introduce bugs.

What coverage tools are not:

A guarantee that your tests are well written. You can have 100% code coverage, but if the tests are brittle, then it's for nothing.

Istanbul Coverage example

I've put together an example project to demonstrate how to integrate coverage into a project.

git clone https://github.com/philipbeel/example-istanbul-gulp-coverage

You'll need to globally install gulp on your machine in order to run gulp on the CLI:

cd example-istanbul-gulp-coverage
npm install 
npm install gulp -g

The example project implements YACA (Yet Another Calculator App) a crude calculator, with addition and subtraction files located in calculator/js. The project also contains a gulpfile.js and karma.conf.js, we'll walk through this later. For now we just want to run the default gulp task:

gulp

You should see coverage/js/index.html open in your browser with the score of both files, add.js at 100% and subtract.js at 71%.

Clicking into a filename shows line by line details about what code is being covered. I've deliberately left off some tests on subtract.test.js so you can compare the results.

Coverage command explained:

When we executed the gulp command the following events sequence is triggered:

1. The unit:coverage gulp task is executed, which starts a karma test runner and sets up the configuration options
2. The phantom browser runs and the tests are executed inside of it.
3. The output is reported back to the gulpfile, Istanbul then creates a new /coverage directory to store the results.
4. A new browser tab is automatically opened displaying the Istanbul report.

You can extend this example project to implement AMD, or switch mocha for jasmine, as per your requirements.

Further reading

Coverage testing can be valuable component of a wider CI toolchain. If your interested check out some of these valuable resources.

• Jenkins Docker Image
• Sinnon JS unit testing
• Git hooks