Houssein Djirdeh

Progressive React

Wed, 20 Feb 2019 10:00:00 +0000

tl.dr: Want to make your React site more performant? Here's a quick checklist:

Measure component-level rendering performance with either of the following:

Chrome DevTools Performance panel
React DevTools profiler

Minimize unecessary component re-renders

Override shouldComponentUpdate where applicable
Use PureComponent for class components
Use React.memo for functional components
Memoize Redux selectors (with reselect for example
Virtualize super long lists (with react-window for example

Measure app-level performance with Lighthouse
Improve app-level performance

If you are not server-side rendering, split components with React.lazy
If you are server-side rendering, split components with a library like loadable-components
Use a service worker to cache files that are worth caching. Workbox will make your life easier.
If you are server-side rendering, use streams instead of strings (with renderToNodeStream and renderToStaticNodeStream)
Can't SSR? Pre-render instead. Libraries like react-snap can help.
Extract critical styles if you are using a CSS-in-JS library.
Make sure your application is accessible. Consider using libraries like React A11y and react-axe.
Add a web app manifest if you think users would like to access your site through their device homescreen.

Performance advocates, like myself, spend a lot of time “advocating” for faster sites. At times however, we don’t cover framework-specific optimizations that can be important to consider if you use a particular framework for your site.

This article will cover a number of performance optimizations you can add to your React sites. The key idea here is to ensure your site performs well enough so that more people can use it.

Introduction

What does it mean to build a site that more people can use? How does this get measured? Why should this get measured?

Let’s try and answer this question by taking a look at the easiest way to start building a React app - Create React App. A brand new project from scratch has the following dependencies:

The react core library that lets you build things with React components: 2.5 kB
The react-dom library to render your components to the DOM: 30.7 kB
Some initial code including your first component: ~3 kB

The numbers here are from v16.6.3.

WebPageTest can be used to see how long it would take for a brand new CRA application to load on a Moto G4.

This “Hello, World” application is hosted on Firebase and viewed on Chrome with three different network connection types:

4G (9 Mbps)
3G (1.6 Mbps)
3G Slow (400 Kbps)

Some latency needs to be accounted as well.

Why use a Moto G4? It’s a low-end mobile phone similar to what many people use in developing countries as their primary device. On 4G, the application finishes loading in 2 seconds. In 3G Slow, it takes more than 4 seconds for the page to become interactive.

As interesting as these numbers may seem, they aren’t very useful if you don’t know who your users are. Your definition of slow can be completely different from mine or somebody else’s, and your perception on how fast a site loads can be skewed to the device and network connection that you use. Including a desktop machine (with cable connection) in this experiment shows how drastic the difference can be:

Can we measure the current state of performance?

A typical React application can contain many components and third-party libraries. This means that the performance of a “Hello World” app doesn’t give much insight into how fast an actual application might load, but is there a way to track how well a majority of sites that use a specific tool (like React) perform?

HTTP Archive might be able to help. It’s an open-source attempt to keep track of how the web is built, and it does this by crawling over a million sites every month, running them through WebPagetest, and then storing information about them. This includes the number of requests, loading metrics, size of payloads, and so on.

Library-Detector-for-Chrome is a Chrome extension that can detect which JavaScript libraries are used on a page. It was recently included as a diagnostic audit to Lighthouse which means that this information can be queried en masse through HTTP Archive. This can help provide a way to analyze results of thousands of sites that use a specific JavaScript library (the React detection mechanism lives here).

The complete HTTP Archive dataset is public and available on BigQuery. After querying over 140,000 domains in emulated mobile conditions (2019_01_01 dataset) that use React, the following results were found:

Median First Meaningful Paint: 6.9s
Median Time to Interactive: 19.7s

Almost 20 seconds for a site to become interactive is no joke, but it’s not uncommon to see on large sites using weaker devices and network connections. Also, there are a few reasons why you should take these numbers with a grain of salt:

There are a lot of other factors involved that affect the performance of a site, such as the total amount of JavaScript that gets shipped, the number of images and other assets rendered on a page and so forth. It’s not fair to measure site performance against a single horizontal (“is React is used on a page” for example) if all of these other factors aren’t taken into account.
Replace “React” with any other client-side framework/library in that query and you’ll see similar numbers.

There’s a lot of work that needs to be done before an accurate assessement can be made for how sites in the wild that use a particular library generally perform.

MOAR JavaScript

One thing that is not specific to a particular library is the amount of JavaScript that we’re generally shipping over the wire. The HTTP Archive already provides a handy report for this, but in short, the median JavaScript bytes sent were:

74.7 KB for mobile webpages in December 15, 2011
384.4 KB for mobile webpages in December 15, 2018

But wait, this includes over a million URLs! There has to be thousands of random sites that skew these results right?

Fair point. Let’s try to find the same results but for the top 10,000 Alexa sites:

381.5 KB for mobile webpages in December 15, 2018 (Query)

As a whole, we’re building websites that ship more JavaScript than we did seven years ago, and this makes sense. Sites have become bigger, more interactive and more complex and this number is still gradually increasing in an upward trend year after year. You may have already heard this before, but the more JavaScript you send to the browser, the more time it needs to be parsed, compiled and executed. Consequently, this slows down your site.

It’s important to note that every site and user base is different. Many developers that ship over 300 KB of JavaScript do not have a problem with how well it performs for most of their users, and that’s fine. However, if you happen to be concerned that the performance of your React site could be better for your users, profiling is always a good first step.

Profiling / Analyzing

Profiling and analyzing a React application can be looked at as a two-fold approach:

Component-level performance: This affects how users actually interact with your site. Clicking a button to load a list should feel snappy, but it most likely won’t be if hundreds of components are re-rendering when they shouldn’t.
Initial app-level performance: This affects how soon users can begin interacting with you site. The amount of code that gets shipped to your users as soon as they load the first page is an example of a factor that affects this.

Measure component-level performance

To try and summarize the concept of React’s reconciliation algorithm, or the “virtual DOM”, in a single sentence: React takes steps to diff between a newer DOM tree and an older tree to figure out what needs to be updated in the UI when data is changed within a component. This makes things a lot less performance intensive than re-rendering the entire application with every state/prop change (a difference between O(N³) and O(N)).

Even with these optimizations baked into React internals, you can always run into the problem of having components in an application re-render when they shouldn’t. This might not be noticeable for smaller applications, but it can degrade performance significantly if hundreds of components are being rendered on a page.

There are a number of reasons why components render when they shouldn’t - functions within a component might not be as efficient as they could be, or maybe an entire list of components are being re-rendered when only a single component gets added onto a list. There are tools that you can use to identify which component trees are taking too long to render, such as:

Chrome DevTools Performance panel
React DevTools profiler

Analyze performance with the Chrome DevTools Performance Panel

React uses the User Timing API to measure the time a component takes for each step of its lifecycle. You can run performance traces using Chrome DevTools to analyze how efficiently your components mount, render, and unmount during page interactions or reloads.

The User Timing API is only used during development and is disabled in production mode. A faster implementation that can be used during production without significantly harming performance was one of the motivations behind building a newer Profiler API..

Analyze performance with the React DevTools Profiler

With react-dom 16.5, a newer Profiler panel within React DevTools can be used to trace how well your components are rendering in terms of performance. It does this by using the Profiler API to collect timing information for every component that re-renders.

The Profiler panel lives as a separate tab within React DevTools. Similar to the Performance panel in Chrome DevTools, you can record user interactions and page reloads to analyze how well your components are performing.

You can switch between different commits, or states when DOM nodes are added, removed, or updated, to get more nuanced data of which components are taking their sweet time to render.

These screenshots are from profiling a single user interaction in a simple app which involves fetching a list of trending GitHub repos when a button is clicked. As you can see, there are only two commits:

One for a loading indicator that shows when the list of items are fetched
One after the API call is completed and the list is populated to the DOM

The right hand side shows other useful metadata including commit information or component-specific data such as props and state.

To complicate things up a bit, consider the same example but with multiple API calls being fired to load specific trending repositories based on programming language (JavaScript, Golang, etc…). As expected, there are more commits now:

The later commits all have longer and more yellow bars in the chart. This means that the time it takes for all the components to finish rendering takes longer as the list on the page grows. This happens because every component in the list re-renders with each new API call. This helps identify an issue that can be resolved relatively quickly: every single item on the list does not need to be re-rendered when new items are being added.

Minimize unecessary re-renders

There are quite a few ways to minimize and remove unecessary re-renders in a React app:

Override shouldComponentUpdate

shouldComponentUpdate(nextProps, nextState) {
  // return true only if a certain condition is met
}

Use PureComponent for class components

import React, { PureComponent } from 'react';

class AvatarComponent extends PureComponent {

}

Use memo for functional components

import React, { memo } from 'react';

const AvatarComponent = memo(props => {

});

Memoize Redux selectors (with reselect for example)
Virtualize super long lists (with react-window for example)

Measure app-level performance

Aside from specific DOM mutations and component re-renders, there are other higher level concerns worth profiling for as well. Lighthouse makes it easy to analyze and assess how a particular site performs.

There are three ways to run Lighthouse tests on a webpage:

Node CLI
Chrome Extension
Directly through Chrome DevTools in the Audits panel

Lighthouse usually takes a little time gathering all the data it needs from a page and then auditing it against a number of checks. Once that’s complete, it generates a report with all of the final information.

A number of audits can be used to identify if the amount of JavaScript being shipped to the browser should be reduced:

Eliminate render-blocking resources
JavaScript boot-up time is too high
Avoid enormous network payloads

If any of these audits fail due to large JavaScript bundles, splitting your bundle should be the very first thing that you consider doing. There’s no reason to load more code than necessary if there is a way split things up.

Split your bundle

One way to code-split is to use dynamic imports:

  
  import('lodash.sortby')
    .then(module => module.default)
    .then(module => doSomethingCool(module))

The import syntax may look like a function call, but it allows you to import any module asynchronously where a promise gets returned. In this example, the sortby method from lodash is imported where doSomethingCool is then fired.

Dynamic imports are a relatively new syntax and are currently in stage 3 of the TC39 process. The syntax is already supported in Chrome and Safari as well as module bundlers like Webpack, Rollup and Parcel.

In the context of React, abstractions have been built to make the process of splitting on the component-level while using dynamic imports even easier. React.lazy is one example:

import React, { lazy } from 'react';

const AvatarComponent = lazy(() => import('./AvatarComponent'));

One of the main concerns of loading different parts of an application asynchronously is handling the delay that a user can experience. For this, the Suspense component can be used to “suspend” a certain component tree from rendering. By using it alongside React.lazy, a loading indicator can be shown as a fallback while a component is still being fetched:

import React, { lazy, Suspense } from 'react';
import LoadingComponent from './LoadingComponent';

const AvatarComponent = lazy(() => import('./AvatarComponent'));

const PageComponent = () => (
  <Suspense fallback={LoadingComponent}>
    <SomeComponent />
  </Suspense>
)

Suspense does not yet work if your views are rendered on the server. If you would like to code-split in a server-side rendered React app, use a library like loadable-components as suggested in the React docs.

import React from 'react';
import loadable from '@loadable/component'
import LoadingComponent from './LoadingComponent';

const AvatarComponent =
  loadable(() => import('./AvatarComponent'), {
    LoadingComponent: () => LoadingComponent
  });

Loading components can also be used as indicators with loadable-component while the main component is still being fetched.

Code-split on scroll?

Another handy library that provides a wrapper around loadable-components and Intersection Observer is react-loadable-visibility. You can use it to load components as they become visible within the device viewport when the user scrolls the page.

import React from 'react';
import loadableVisibility from 'react-loadable-visibility/loadable-components'

const AvatarComponent = loadableVisibility(() => import('./AvatarComponent'), {
  LoadingComponent: Loading,
})

Cache things worth caching

A service worker is a web worker that runs in the background of your browser when you view a webpage.

The idea behind service workers is to include specific functionality on a separate thread that can improve the user experience. This includes caching important files so that when your users make a repeat visit, the browser can make a request to the service worker instead of all the way to the server which improves how fast the page loads on repeat visits.

Workbox is a set of libraries that can make it easier to include service workers without actually writing one from scratch. With CRA 2.0, you only need to remove 2 characters in src/index.js to have a workbox-powered service worker up and running with basic caching functionality.

  
  import React from 'react';

  //...

  // If you want your app to work offline and load faster, you can change
  // unregister() to register() below. Note this comes with some pitfalls.
  // Learn more about service workers: http://bit.ly/CRA-PWA
  serviceWorker.unregister();

Streaming SSR

The basic idea of server-side rendering on a mainly client-rendered application involves shipping down an HTML document from the server that the client would have eventually produced. This allows you to display content to the user much sooner than them waiting for the JS bundle to finish executing.

To make sure this works well, you need to ensure that the browser re-uses the server-rendered DOM instead of re-creating the markup (with hydrate() for example in React). This makes things seem like a page has loaded faster, but it can delay the time it takes for it to become interactive.

With React 16, you can take advantage of streaming while server-side rendering your components. Instead of using renderToString to return an HTML string, you can use renderToNodeStream to return a Node Readable stream of bytes. Streaming from a server allows a client to receive and hydrate different parts of the HTML document instead of all at once. Although SSR should always improve First Paint times in your application, this would reduce that number even further.

Can’t SSR? Pre-render instead

The definition of SSR is a little blurry since there are many different ways servers can ship some, instead of all, the static content needed for a specific URL and how a client can hydrate it. Prerendering, or static rendering, is a middle-ground between entirely server-side rendering pages on the fly and pure client-side rendering. This approach usually involves generating HTML pages for every route during build time and serving that to the user while a JavaScript bundle finishes compiling.

If you would like to introduce pre-rendering into your application, libraries like react-snap that take advantage of Puppeteer can make things easier for you.

Extract critical CSS-in-JS styles

Many developers in the React community use CSS-in-JS libraries like emotion and styled-components for a multitude of reasons (component-scoped styles, automatically generated selectors adjusted properties based on props, etc…). If you’re not entirely careful, you can run into the issue of having all the styles being computed at runtime. This means that the styles only get applied when the JavaScript bundle finishes executing which can trigger a flash of unstyled content. Like most performance concerns, this gets exemplified if your user happens to have a weaker mobile device or poorer network connection.

Screenshot from denar90

If you’ve already incorporated some sort of server-side rendering into your application, you can fix this by extracting critical styles. Both emotion and styled-components support this out of the box where you can extract your styles into a Readable node stream. Glamor has a separate library that allows you to do the same thing as well.

Extracting critical styles can improve things quite substantially for users with weaker devices or network connections:

This is actually a Preact app, but you get the idea :) (optimizations by denar90)

Make things accessible

The term “progressive” usually means that an attempt was made to ensure that all users have the opportunity to access at least some content of the site, if not all of it. If you don’t ensure that your site is accessible to users with a disability, it is not progressive.

Lighthouse is a good first step to identify any accessibility concerns on a web page. To find issues that are more specific to React elements, React A11y can help.

You can also consider using react-axe to audit the final, rendered DOM instead of just the JSX in your application.

Improve the experience when users install the site to their home screen

Does your React site work well on mobile? Do you have a service worker that caches some content so that it works offline? Is your application useful enough that you think people would like to access it on their device homescreen?

If you answered yes to all these questions, add a web app manifest to your site so that your users can get a better mobile experience when it’s “installed” on their device. This lets you change a number of settings including the app icon, background color and theme color.

Create React App already sets up a default manifest for you when you create a new app:

{
  "short_name": "React App",
  "name": "Create React App Sample",
  "icons": [
    {
      "src": "favicon.ico",
      "sizes": "64x64 32x32 24x24 16x16",
      "type": "image/x-icon"
    }
  ],
  "start_url": ".",
  "display": "standalone",
  "theme_color": "#000000",
  "background_color": "#ffffff"
}

Miscellaneous

The new few sections will cover techniques commonly used to only improve developer experience but also have the advantage of minimizing the amount of code written.

Why is this useful? Less code = less bytes shipped = faster web page.

Atomic CSS

The idea behind Atomic styling is to define single-use classes that are focused, small and identifiable. For example, a single class would be used to add a blue background to a button:

<button class="bg-blue">Click Me</button>

A separate class would be responsible for giving it a specific amount of padding:

<button class="bg-blue pa2">Click Me</button>

And so on. Although this would add a lot more values to the class attribute for most of your DOM nodes, you get the added benefit of not writing nearly as much CSS as you normally would if you use a library that sets up all the selectors for you. Tachyons is one example of such a library.

Scoping styles to components using atomic utility classes has become a common styling pattern for many developers. Libraries such as tachyons-components even let you apply these styles using a styled-components like API:

import styled from 'tachyons-components'

const Button = styled('button')`
  bg-blue pa2
`

<Button>Click Me</Button>

Although it may not be the primary reason why developers use atomic utility libraries like, removing the need to create new CSS selectors by relying entirely on a fixed set of single-use classes means that the amount of CSS shipped to the browser never changes.

Hooks

Hooks allow you to do a bunch of things with functional (no-class) components that you could have only previously done with class components. Including state is one example:

import { useState } from 'react';

function AvatarComponent() {
  const [name, setName] = useState('Houssein');

  return (
    <React.Fragment>
      <div>
        <p>This is a picture of {name}</p>
        <img src="avatar.png" />
      </div>

      <button onClick={() => setName('a banana')}>
        Fix name
      </button>
    </React.Fragment>
  );
}

Hooks can be useful for:

Including state into a component without using a class (useState)
Including side effects without using a class (useEffect)
Re-using logic between components by creating your own hooks.

This all lets you incorporate logic into your components in such a way that it can be reused in other places of your application. Prior to hooks, recompose was commonly used to get some of these capabilities.

Although most developers will decide to use Hooks to improve the experience of tying logic into their components, it can also help cut down bundle sizes.

In terms of the implementation size, the Hooks support increases React only by ~1.5kB (min+gzip). While this isn’t much, it’s also likely that adopting Hooks could reduce your bundle size because code using Hooks tends to minify better than equivalent code using classes.

Making Sense of React Hooks

Conclusion

When a open-source tool, like React, ends up being used by so many developers - it’s natural to expect two things:

Improved APIs within the tool to make building applications easier
New third-party libraries built by the community that help make building applications easier

“…make building applications easier” can mean a lot of things, and shipping apps that load faster with less effort is just a part of it.

Looking back at 2018 - and a note on being grateful, helpful, and empathetic

Wed, 02 Jan 2019 07:30:00 +0000

Some things I did last year:

Joined the Web Developer Relations team at Google.
Moved to California.
Completed and launched Full Stack React Native.
Gave talks at a few places:
Shipped a few open-source projects including Progressive Tooling.
Built something with Golang for the first time.
Helped maintain GitPoint with some amazing contributors.

Some other things:

I think I found a better balance. It’s easy to get overwhelmed and burnt out, and I’ve been close a few times. I still think I’m managing my time a little better however.
Imposter syndrome is still my good friend seven days of the week. This won’t change anytime soon.
I’m still learning how to skateboard and swim!

Being grateful

A lot of people seem to think that I’ve been building websites and writing JavaScript for a very long time, but that’s simply not true. I wrote my first lines of HTML and CSS in the summer of 2015. Fast forward three years, and I started working with so many people that I’ve looked up to since I started building my first website. I still look up to them, and that’s why I enjoy what I do so much.

It’s easy to take things for granted, or to only attribute one’s progress to their hard work and dedication. Don’t get me wrong, everybody should be super proud of the hard work they do to achieve whatever they want to achieve. Hard work and consistency can take anyone far, but there’s always more to it.

I have to thank the countless people I’ve worked with that showed me the ropes, the many open-source contributors that I hacked projects with, the folks that referred me for a new job, and the individuals that nudged me to give my first conference talk. If it weren’t for them, I would not be where I am today.

Being helpful

The one thing I told myself that I need to in last year’s version of this article was to be more helpful, especially to those that are just getting started in web development. I think I helped quite a few people begin their journey and I’m glad I did, but this doesn’t mean that I could not have done more. Let’s hope I only take things a step further in 2019.

This year was also the very first time I began working as a Developer Advocate. I’ve been fascinated about web performance for a while now and have always tried to spend time to help others learn more about the topic. It feels even better to know that this is literally a part of my job now.

Being empathetic

The amazing thing about the front-end community is that people are very passionate. For most of the time, this is great! So many folks share their opinions on tooling, workflow and code that it helps everyone learn more as a result. Nonetheless, I also think that this can be taken a little too far.

I hope we don’t see as many people objecting strongly to the presence of a free, open-source library because they think other solutions that are better already exist. There’s no harm in letting people know your opinion, but there’s a line that gets crossed where it turns to bashing. Everybody is free to use what works for them, and there’s always more than one way to solve a problem.

I also hope we see less of a sentiment that developers are “careless” if their site performs poorly. Everyone has problems that they need to deal with when they build a website, and most people don’t have the same privileges that I do (I get paid to think about web performance). However, I’m glad I work with a team that tries to solve this problem on a daily basis and I look forward to better tooling and improved guidance in 2019.

My plans for next year

Be more grateful, helpful, and empathetic. Everything else will, hopefully, fall into place.

Progressive Web Apps with Angular: Part 2 - Lazy Loading

Wed, 05 Dec 2018 07:30:00 +0000

To explore how to add lazy loading functionality to an Angular app, this article will go through the process of building a relatively small application called Tour of Thrones.

View App Source Code

An API of Ice and Fire (an unofficial, community-built API for Game of Thrones) will be used to list houses from the book series and provide information about them. While building this application, we’ll explore a number of topics including:

Getting started with Angular CLI
Lazy loading on scroll
Lazy loading on route change
Secondary routes

Getting Started

If you have the required Node and NPM versions, you can install Angular CLI with the following command:

npm install -g @angular/cli

You can then create a new application with:

ng new tour-of-thrones

If you have Angular CLI 7 installed or a later version, you should see a few questions pop up in your terminal:

? Would you like to add Angular routing? No
? Which stylesheet format would you like to use?
  CSS
❯ SCSS   [ http://sass-lang.com   ]
  SASS   [ http://sass-lang.com   ]
  LESS   [ http://lesscss.org     ]
  Stylus [ http://stylus-lang.com ]

You can say No to Angular routing for now. We’ll include it manually when we begin to add routing to the application.

Feel free to select whichever stylesheet format you prefer. If you would like to copy over all the styles in this article however, select SCSS.

To start the app:

cd tour-of-thrones
npm start

You should now see Angular’s version of “Hello World”.

The application will consist of two parts:

A base home route that lists all the Game of Thrones houses.

A secondary house route that shows information for a particular house in a modal.

First Component

Building the first few components in the application is a good way to kick things off. We’ll start with the HeaderComponent responsible for showing the name of the application in the home route.

Create a separate components/ directory that contains a separate header/ directory within. This sub-directory can contain all the files needed for HeaderComponent.

Starting with the template file, header.component.html:

<!-- src/app/component/header/header.component.html -->

<div id="header">
  <div class="item"></div>
  <h1>
    Tour Of Thrones
  </h1>
  <div class="item">
    <i class="arrow down"></i>
  </div>
</div>

Now update the also newly created header.component.ts file:

// src/app/component/header/header.component.ts

import { Component } from '@angular/core';

@Component({
  selector: 'app-header',
  templateUrl: './header.component.html',
  styleUrls: ['./header.component.scss'],
})
export class HeaderComponent {}

You can copy and paste the styles for header.component.scss from here. We’ll do this for all the styles in the application.

To simplify how components are imported throughout the app, you can use named exports in the same directory for each component with an index.ts file. Since header/ is the only component directory we currently have, exporting within the index.ts file that lives in the folder:

// src/app/component/header/index.ts

export { HeaderComponent } from './header.component';

Similarly, you can re-export these components one level higher in an index.ts file within the components/ directory:

// src/app/component/index.ts

export { HeaderComponent } from './header';

By default, Angular CLI allows you to import using absolute imports (import ComponentA from 'src/app/component'). Since all of the files live within the app directory here, you can modify baseUrl in tsconfig.json to import directly from app and not src/app:

  
  // tsconfig.json

  {
    "compileOnSave": false,
    "compilerOptions": {
      "baseUrl": "./",
      "baseUrl": "src",
      // ...
    }
  }

Why import/export components like this?

Normally, you would import multiple components from other files to a parent component like this:

import { ComponentA } from '../component/component-a';
import { ComponentB } from '../component/component-b';
import { ComponentC } from '../component/component-c';

You can also use index.ts files to re-export components (or any other exports). These are sometimes referred to as barrel files and allow you to simplify how you can import exports into something like this:

import { ComponentA, ComponentB, ComponentC } from '../component';

Although the latter approach is used in this article, there is no correct way. There are actually a few issues with the second approach. It can make jumping between files within your editor/IDE harder as well as make autocomplete not work as effectively. If you don't like this, feel free to import/export normally instead of how it's done in this article.

The only component (app.component.ts) and module (app.module.ts) scaffolded when the project was created live inside of src/app. You’ll need to modify AppComponent to include HeaderComponent:

<!-- src/app/app.component.html -->

<div id="app">
  <app-header></app-header>
</div>

You can see the styling in app.component.scss here.

You also have to make sure it’s declared in AppModule:

// src/app/app.module.ts

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { HeaderComponent } from 'app/component';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent, HeaderComponent],
  imports: [BrowserModule],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

The last thing you’ll need to do here is to add some global styles to the application (which includes the Thrones-style font). All global styles in an Angular app go to styles.scss at the root of the src/ directory. Take a look here to copy over the styles directly.

Try it out

If you run the application, you’ll notice that the header component renders and takes up a little more than half the screen.

Base Route

Now that you’ve got your feet wet building the first component, let’s move on to building everything necessary for the base /home route. We’ll need:

A card component to display the information of each house
A routing system in place to define a /home route
A service to interface with our external API

We’ll start with CardComponent. Similarly, create a card/ subdirectory within components/ with all of its files:

<!-- src/app/component/card/card.component.html -->

<div (click)="onClick()" class="card grow" [ngStyle]="setBackgroundStyle()">
  <h3>{{name}}</h3>
</div>

// src/app/component/card/card.component.ts

import { Component, Input, Output, EventEmitter } from '@angular/core';

@Component({
  selector: 'app-card',
  templateUrl: './card.component.html',
  styleUrls: ['./card.component.scss'],
})
export class CardComponent {
  @Input() id: Number;
  @Input() name: string;
  @Input() color: string;
  @Output() click = new EventEmitter<any>();

  onClick() {
    this.click.emit({
      id: this.id,
    });
  }

  setBackgroundStyle() {
    return {
      background: `radial-gradient(${this.color}, #39393f)`,
      'box-shadow': `0 0 60px ${this.color}`,
    };
  }
}

// src/app/component/card/index.ts

export { CardComponent } from './card.component';

Finally, you’ll need to update the top-level barrel file:

// src/app/component/index.ts

export { CardComponent } from './card';
export { HeaderComponent } from './header';

Input binding is used to pass an id parameter (the house ID) as well the house name and color. The color isn’t fetched from the API, but is randomly generated to add a little spicyness 🌶 to the app. You’ll see this in a bit.
ngStyle is used to add box-shadow and background CSS properties using this color.
An EventEmitter is used to fire a click event to a parent component. We pass the house id into this event as well.

The styles for the card component can be found here. Lastly, you’ll need to declare this component in AppModule in order to use it:

// src/app/app.module.ts

// ...

import { HeaderComponent, CardComponent } from 'app/component';

@NgModule({
  declarations: [AppComponent, HeaderComponent, CardComponent],
  // ...
})
// ...

Try it out

Let’s add a couple of dummy card components to AppComponent to see if they’re displaying correctly:

<!-- src/app/app.component.html -->

<div id="app">
  <app-header></app-header>
  <app-card id="1" name="House Freshness" color="green"></app-card>
  <app-card id="2" name="House Homes" color="red"></app-card>
  <app-card id="3" name="House Juice" color="orange"></app-card>
  <app-card id="4" name="House Replay" color="blue"></app-card>
</div>

Cards are being rendered! They don’t have any specific widths/heights assigned to them and they take the shape of their parent container, which is expected. Once we add the home route next, we’ll use CSS grid to give our cards some structure.

Routing

It’s time to begin adding some navigation to the application. Instead of placing components that make up the routes in the component/ directory, we’ll put them in a separate directory called scene/.

Create a separate scene/ directory with a home/ subdirectory. Add all the files for HomeComponent responsible for the initial route can be added here:

<!-- src/app/scene/home/home.component.html -->

<div class="grid">
  <app-card 
    *ngFor="let house of houses" 
    [id]="house.id" 
    [name]="house.name" 
    [color]="house.color">
  </app-card>
</div>

<!-- src/app/scene/home/home.component.ts -->

import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-home',
  templateUrl: './home.component.html',
  styleUrls: ['./home.component.scss'],
})
export class HomeComponent implements OnInit {
  houses = [];

  constructor() {}

  ngOnInit() {
    this.getHouses();
  }

  getHouses() {
    this.houses = [
      {id: 1, name: 'House Freshness', color: 'green'},
      {id: 2, name: 'House Homes', color: 'red'},
      {id: 3, name: 'House Juice', color: 'orange'},
      {id: 4, name: 'House Replay', color: 'blue'},
    ];
  }
}

// src/app/scene/home/index.ts

export { HomeComponent } from './home.component';

// src/app/scene/index.ts

export { HomeComponent } from './home';

The styles for this component can be found here. If you take a look at the styles, you’ll notice that the list of cards is wrapped in a grid structure.

Now let’s define the routes in AppModule:

// src/app/app.module.ts

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { Routes, RouterModule } from '@angular/router';

import { HeaderComponent, CardComponent } from 'app/component';
import { HomeComponent } from 'app/scene';
import { AppComponent } from './app.component';

const routePaths: Routes = [
  {
    path: '',
    redirectTo: 'home',
    pathMatch: 'full',
  },
  {
    path: 'home',
    component: HomeComponent,
  },
];

@NgModule({
  declarations: [AppComponent, HeaderComponent, CardComponent, HomeComponent],
  imports: [BrowserModule, RouterModule.forRoot(routePaths)],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

We’ve defined a single route path (home) that maps to a component (HomeComponent) and we’ve set up the root path to redirect to this. You now need to let the application know where to dynamically load the correct component based on the current route, and you can do that by using router-outlet:

<!-- src/app/app.component.html -->

<div id="app">
  <app-header></app-header>
  <router-outlet></router-outlet>
</div>

Try it out

Take a look at the application now. You’ll see HomeComponent showing the list of houses in a grid structure.

You can also see that loading the base URL of the application immediately redirects to /home.

Service

To get some real data, we need to interface with the API. Create a service for this by placing it in a /service directory:

// src/app/service/iceandfire.service.ts

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Observable } from 'rxjs';
import { map, filter, scan } from 'rxjs/operators';

import { House } from 'app/type';

@Injectable()
export class IceAndFireService {
  baseUrl: string;

  constructor(private http: HttpClient) {
    this.baseUrl = 'https://anapioficeandfire.com/api';
  }

  fetchHouses(page = 1) {
    return this.http.get<House[]>(`${this.baseUrl}/houses?page=${page}`);
  }

  fetchHouse(id: number) {
    return this.http.get<House>(`${this.baseUrl}/houses/${id}`);
  }
}

We’re using Angular’s HttpClient to interface with the API by defining two separate methods:

fetchHouses: Get a list of houses given a page number
fetchHouse: Get information about a particular house

We’ll also wrap our service in its own module:

// src/app/service/service.module.ts

import { NgModule } from '@angular/core';
import { IceAndFireService } from './iceandfire.service';

@NgModule({
  imports: [],
  exports: [],
  declarations: [],
  providers: [],
})
export class ServicesModule {
  static forRoot() {
    return {
      ngModule: ServicesModule,
      providers: [IceAndFireService],
    };
  }
}

export { IceAndFireService };

// src/app/service/index.ts

export { IceAndFireService } from './iceandfire.service';
export { ServicesModule } from './service.module';

In the service, we type-check with a House interface. You can add the types and interfaces to a type/ directory:

// src/app/type/house.ts
type Url = string;

export interface House {
  id: number;
  url: Url;
  name: string;
  region: string;
  coatOfArms: string;
  words: string;
  titles: string[];
  seats: string[];
  currentLord: string;
  heir: string;
  overlord: Url;
  founded: string;
  founder: string;
  diedOut: string;
  ancestralWeapons: string[];
  cadetBranches: Url[];
  swornMembers: Url[];
  color: string;
}

// src/app/type/index.ts

export { House } from './house';

Now import the services module in AppModule:

// src/app/app.module.ts

//...
import { HttpClientModule } from '@angular/common/http';
import { ServicesModule } from 'app/service';
//...

@NgModule({
  //...
  imports: [
    //...
    HttpClientModule,
    ServicesModule.forRoot(),
  ],
  //...
})
export class AppModule {}

You can now update HomeComponent to use the appropriate service method:

// src/app/scene/home/home.component.ts

import { Component, OnInit } from '@angular/core';

import { IceAndFireService } from 'app/service';
import { House } from 'app/type';

@Component({
  selector: 'app-home',
  templateUrl: './home.component.html',
  styleUrls: ['./home.component.scss'],
})
export class HomeComponent implements OnInit {
  pageNum = 1;
  houses: House[] = [];

  constructor(private service: IceAndFireService) {}

  ngOnInit() {
    this.getHouses();
  }

  getHouses() {
    this.houses = [
      {id: 1, name: 'House Freshness', color: 'green'},
      {id: 2, name: 'House Homes', color: 'red'},
      {id: 3, name: 'House Juice', color: 'orange'},
      {id: 4, name: 'House Replay', color: 'blue'},
    ];
  }

  getHouses(pageNum = 1) {
    this.service.fetchHouses(pageNum).subscribe(
      data => {
        this.houses = this.houses.concat(
          data.map(datum => {
            const urlSplit = datum.url.split('/');

            return {
              ...datum,
              id: Number(urlSplit[urlSplit.length - 1]),
              color: getColor(),
            };
          }),
        );
      },
      err => console.error(err),
    );
  }
}

// utils
const getColor = () =>
  `#${Math.random()
    .toString(16)
    .slice(-6)}66`;

Let’s quickly go over what’s happening here:

We’re importing IceAndFireService and injecting it into the component constructor
We’re using the OnInit lifecycle hook to fire the getHouses class method as soon as our component finishes initializing
In the service, this.http.get returns an observable. In the component, the getHouses method calls the fetchHouses method and subscribes to the observable returned. Since the API does not have a specific ID attribute for each object, we’re mapping through the response and obtaining the ID from the URL attribute as well as assigning a color to each house.
At the end, we have getColor. This is a tiny utility method that returns a color that gets assign for each house. This isn’t exactly random, but it works for now. Also the two digits at the end of the string, 66, represent alpha transparency.

Try it out

If you take a look at the application now, you’ll see the first page of houses rendered as soon as you load the application:

Lazy Loading

To improve loading times on a web page, we can try to lazy load non-critical resources where possible. In other words, we can defer the loading of certain assets until the user actually needs them.

In this application, we’re going to lazy load on two different user actions:

On scroll
On route change

Infinite scrolling

Infinite scrolling is a lazy loading technique to defer loading of future resources until the user has almost scrolled to the end of their currently visible content.

In this application, we want to be careful with how many houses we fetch over the network as soon as the page loads. Like many APIs, the one we’re using paginates responses which allows us to pass a ?page parameter to iterate over responses. We can add infinite scrolling here to defer loading of future paginated results until the user has almost scrolled to the bottom of the web page.

There is more than one way to lazy load elements that show below the edge of the device viewport:

Using scroll event listeners
Using Intersection Observer

For this application, we’ll use ngx-infinite-scroll, a community-built library that provides an Angular directive abstraction over changes to the scroll event. With this library, you can listen and fire callback events triggered by scroll behaviour.

npm install ngx-infinite-scroll --save

You can now import its module into the application:

// src/app/app.module.ts

//...
import { InfiniteScrollModule } from 'ngx-infinite-scroll';
//...

@NgModule({
  imports: [
    //...
    InfiniteScrollModule,
  ],
  //...
})
export class AppModule {}

And add it to HomeComponent:

<!-- src/app/scene/home/home.component.html -->

<div class="grid" infinite-scroll (scrolled)="onScrollDown()">
  <app-card 
    *ngFor="let house of houses" 
    [id]="house.id" 
    [name]="house.name" 
    [color]="house.color" 
    (click)="routeToHouse($event)">
  </app-card>
</div>

// src/app/scene/home/home.component.ts

import { Component, OnInit } from '@angular/core';

import { IceAndFireService } from 'app/service';
import { House } from 'app/type';

@Component({
  selector: 'app-home',
  templateUrl: './home.component.html',
  styleUrls: ['./home.component.scss'],
})
export class HomeComponent implements OnInit {
  //...

  onScrollDown() {
    this.pageNum++;
    this.getHouses(this.pageNum);
  }
}

We just added onScrollDown as a callback for the directive scrolled method. In here, we increment the page number and call the getHouses method.

Now if you try running the application, you’ll see houses load as you scroll down the page.

The library allows users to customize a number of attributes such as modifying the distance of the current scroll location with respect to the end of the container that determines when to fire an event. You can refer to the README for more information.

When should we lazy load on scroll?

There are countless ways to organize a paginated list of results in an application like this, and an infinitely long list is definitely not the best way. Many social media platforms (such as Twitter) use this model to keep users engaged, but it is not suitable for when the user needs to find a specific piece of information quickly.

In this application for example, it would take a user a very long time to find information about a particular house. Adding normal pagination, allowing the user to filter by region or name, or allowing them to search for a particular house are all probably better ways of doing this.

Instead of trying to lazy load all the content that is displayed to the user as they scroll (i.e. infinite scroll), it might be more worthwhile to try and defer loading of certain elements that aren’t immediately visible to users on page load. Elements such as images and video can consume significant amounts of user bandwidth and lazy loading them specifically will not necessarily affect the entire paginated flow of the application.

How should we lazy load on scroll?

Finding a library that makes it easier to lazy load elements but uses scroll event listeners is a start. If possible however, try to find a solution that relies on IntersectionObserver but also provides a polyfill for browsers that do not yet support it. Here’s a handy article that shows you how to create an Angular directive with IntersectionObserver.

Code splitting

Code splitting refers to the practice of splitting the application bundle into separate chunks that can be lazy loaded on demand. In other words, instead of providing users with all the code that makes up the application when they load the very first page, you can give them pieces of the bundle as they navigate throughout the app.

You can apply code splitting in different ways, but it commonly happens on the route level. Webpack, the module bundler used by Angular CLI, has code splitting built-in. Without needing to dive in to the internals of our Webpack configurations in order to make this work, Angular router allows you to lazy-load any feature module that you build.

Let’s see this in action by building our next route, /house, which shows information for a single house:

<!-- src/app/scene/house/house.component.html -->

<app-modal (modalClose)="modalClose()">
  <div modal-loader *ngIf="!house; else houseContent" class="loader-container">
    <app-loader></app-loader>
  </div>
  <ng-template #houseContent modal-content>
    <div class="container">
      <h1>{{house.name}}</h1>
      <div *ngIf="house.words !== ''" class="subheading">{{house.words}}</div>
      <div class="info" [ngClass]="(house.words === '') ? 'info-large-margin' : 'info-small-margin'">
        <div class="detail">
          <p class="caption">Coat of Arms</p>
          <p class="body">{{house.coatOfArms === '' ? '?' : house.coatOfArms}}</p>
        </div>
        <div class="detail">
          <p class="caption">Region</p>
          <p class="body">{{house.region === '' ? '?' : house.region}}</p>
        </div>
        <div class="detail">
          <p class="caption">Founded</p>
          <p class="body">{{house.founded === '' ? '?' : house.founded}}</p>
        </div>
      </div>
    </div>
  </ng-template>
</app-modal>

The HouseComponent shows a number of details for the house selected. It is rendered within a modal and for that reason, its contents are wrapped within an <app-modal> component. We’re not going to into too much detail on how this modal component files are written, but you can find them here.

One important thing to mention is that we’re using projection (ng-content) to project content into our modal. We either project a loading state (modal-loader) if we don’t have any house information yet or modal content (modal-content) if we do. You can find the code that makes up our loader here.

Although we’re only using our modal wrapper for a single component in this application, projection is used to make it more reusable. This can be useful if we happen to need to use a modal in any other part of the application.

Unlike the HomeComponent which is being bundled directly with the root AppModule, you can create a separate feature module for HouseComponent that can be lazy loaded:

// src/app/scene/house/house.module.ts

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { RouterModule, Routes } from '@angular/router';

import { ModalComponent, LoaderComponent } from 'app/component';

import { HouseComponent } from './house.component';

const routes: Routes = [
  {
    path: '',
    component: HouseComponent,
  },
];

@NgModule({
  imports: [CommonModule, RouterModule, RouterModule.forChild(routes)],
  declarations: [HouseComponent, ModalComponent, LoaderComponent],
  exports: [HouseComponent, RouterModule],
})
export class HouseModule {}

Now let’s move on to the logic behind this component:

// src/app/scene/house/house.component.ts

import { Component, OnInit } from '@angular/core';
import { Router, ActivatedRoute } from '@angular/router';

import { IceAndFireService } from 'app/service';
import { House } from 'app/type';

@Component({
  selector: 'app-house',
  templateUrl: './house.component.html',
  styleUrls: ['./house.component.scss'],
})
export class HouseComponent implements OnInit {
  house: House;

  constructor(
    private service: IceAndFireService,
    private router: Router,
    private route: ActivatedRoute,
  ) {}

  ngOnInit() {
    this.route.params.subscribe(params => {
      this.service
        .fetchHouse(+params['id'])
        .subscribe(data => (this.house = data), err => console.error(err));
    });
  }

  modalClose() {
    this.router.navigate([{ outlets: { modal: null } }]);
  }
}

In here, we subscribe to our route parameters after the component finishes initializing in order to obtain the house ID. We then fire an API call to fetch its information.

We also have a modalClose method that navigates to a modal outlet with a value of null. We do this to clear our modal’s secondary route.

Secondary routes

In Angular, we can create any number of named router outlets in order to create secondary routes. This can be useful to separate different parts of the application in terms of router configurations that don’t need to fit into the primary router outlet. A good example of using this is for a modal or popup.

Let’s begin by defining the second router outlet:

<!-- src/app/app.component.html -->

<div id="app">
  <app-header></app-header>
  <router-outlet></router-outlet>
  <router-outlet name="modal"></router-outlet>
</div>

Unlike the primary router outlet, secondary outlets must be named. For this example, we’ve named it modal.

Now add HomeModule into the top-level route configurations while lazy loading it. This can be done by using a loadChildren attribute:

// src/app/app.module.ts

//....

const routePaths: Routes = [
  {
    path: '',
    redirectTo: 'home',
    pathMatch: 'full',
  },
  {
    path: 'home',
    component: HomeComponent,
  },
  {
    path: 'house/:id',
    outlet: 'modal',
    loadChildren: 'app/scene/house/house.module#HouseModule',
  },
];

@NgModule({
  //...
})
export class AppModule {}

Although using a loadChildren attribute with a value of the path to the module would normally work, there’s an open issue about a bug that occurs while lazy loading a module tied to a named outlet (secondary route).

In the same issue thread, somebody suggests a workaround that involves adding a route proxy component in between:

// src/app/app.module.ts

import {
  //...
  RouteProxyComponent,
} from 'app/component';

//...

const routePaths: Routes = [
  {
    path: '',
    redirectTo: 'home',
    pathMatch: 'full',
  },
  {
    path: 'home',
    component: HomeComponent,
  },
  {
    path: 'house/:id',
    outlet: 'modal',
    component: RouteProxyComponent,
    children: [
      {
        path: '',
        loadChildren: 'app/scene/house/house.module#HouseModule',
      },
    ],
  },
];

@NgModule({
  //...
  declarations: [
    RouteProxyComponent,
  ],
  //...
})
export class AppModule {}

This workaround works for now, but it does add an extra component layer in between. You can see how the RouteProxyComponent is nothing more than a single router outlet here.

The last thing you’ll need to do is allow the user to switch routes when a house is clicked:

// src/scene/home/home.component.ts

import { Router } from '@angular/router';

//...

export class HomeComponent implements OnInit {
  //...

  constructor(private service: IceAndFireService, private router: Router) {}

  //...

  routeToHouse(event: { id: number }) {
    if (event.id) {
      this.router.navigate([{ outlets: { modal: ['house', event.id] } }]);
    }
  }
  
  //...
}

A routeToHouse method that navigates to a modal outlet with an array for link parameters was added here. Since HouseComponent looks up the ID of the house in our route parameters, we’ve included it here in the array.

Now add a click handler to bind to this event:

<!-- src/scene/home/home.component.html -->

<div class="grid" infinite-scroll (scrolled)="onScrollDown()">
  <app-card 
    *ngFor="let house of houses" 
    [id]="house.id" 
    [name]="house.name" 
    [color]="house.color"
    (click)="routeToHouse($event)">
  </app-card>
</div>

Try it out

Load the application with these changes and click on any house.

If you have the Network tab of your browser’s developer tools open, you’ll notice that the code that makes up the house module is only loaded when you click on a house.

When should we code split?

It depends. In this example, the code that makes up the lazy loaded feature module is less than 3KB minified + gzipped (on a production build). If you think this does not warrant code splitting, you might be right.

Lazy loading feature modules can be a lot more useful when your application starts growing with each module making up a juicy cut of the entire bundle. Many developers think code-splitting should be one of the first things to consider when trying to improve the performance of an application, and rightly so.

Tweet Source

Building feature modules is useful to separate concerns in an Angular application. As you continue to grow your Angular app, you’ll most likely reach a point where you realize that code-splitting some modules can cut down the initial page size significantly.

Conclusion

In this article, we built an Angular 7 app from scratch as well as explored how lazy loading can be useful to optimize its performance. I was planning to also cover @angular/service-worker and how it fits into the CLI in this post, but it turned out to be a bit longer than I expected :). We’ll explore that in the next part of the series.

Thinking PRPL - A Progressive Web Pattern

Mon, 18 Jun 2018 07:30:00 +0000

The PRPL pattern is not a specific technology or tool, but rather a methodology for building web applications that load fast and reliably.

First and foremost, you send (push) the most critical resources to your users.
You do this in order to render your initial route as soon as possible.
You then pre-cache remaining assets.
Finally, you can consider lazy loading your routes.

The term PRPL was coined by the Polymer team in their talk at Google I/O 2016.

Mobile Web

It is probably safe to assume that the majority of individuals who read this article own a mobile device, and the amount of time that we spend on our smartphones and tablets have only increased year after year.

In comScore’s 2017 U.S. Mobile App Report, it was found that the average user spends 16x more time on popular native apps than the mobile web. As mobile device consumers, we are far more likely to spend more time on native apps than we do on the mobile browser. However, mobile web pages still received over twice as many unique monthly visitors than native apps. This is due to a multitude of reasons, including the convenience, security and simplicity of just typing a URL into an address bar instead of installing an entire application.

So how can we ensure that users who discover our web pages have a great experience regardless of what device they use? There are quite a few ways, and we’ll go through some specific techniques and resource hints in this article. But before we do that, let’s take a little time to talk about how the web works first.

When we open a browser on a mobile device (or tablet or desktop) and type something into the address bar and press Enter, a request is sent to a remote server somewhere.

After a certain period of time, the server responds with content that the browser needs. This usually takes shape of an HTML document. The underlying application protocol used by the web (HTTP) works using this request-response pattern.

Once the browser retrieves the initial HTML document, the next thing it does is parse through the contents of the file in order to determine what other resources it needs. For each external resource that it finds, it submits a separate request for it. These resources can include CSS files for styling, JavaScript for dynamic content or even static images. Multiple round trips are usually needed for a typical webpage in order to get all of the content that the user needs to see.

Link Preload

Let’s assume that the following markup represents the HTML document that our browser receives on the initial request:

<html lang="en">
   <head>
      <link rel="stylesheet" href="styles.css">
   </head>
   <body>
      <!--(>'-')> <('-'<)-->
      <script src="script.js"></script>
   </body>
</html>

We can see that there’s a style sheet file that is referenced as well as a JavaScript file. One thing we can do in order to help the fact that multiple requests are needed is to leverage preload:

<html lang="en">
   <head>
      <link rel="preload" as="script" href="script.js">
      <link rel="stylesheet" href="styles.css">
   </head>
   <body>
      <!--(>'-')> <('-'<)-->
      <script src="script.js"></script>
   </body>
</html>

The preload hint has a syntax that a lot of us may already be familiar with:

<link rel="preload" as="script" href="script.js">

It’s a <link> element where we define the location of the file as an href attribute. We specify the preload keyword using the rel attribute and the type of file we’re trying to load using as. In this case, we’re trying to preload a JavaScript file - hence why we’ve defined as="script".

Using preload allows us to inform the browser that a resource is needed immediately after the page loads. In other words, we’re telling the browser that this is a critical resource so please start loading it as soon as you can.

Although we can specify preload tags for resources defined in the head or body of our root HTML file, you’re more likely to get the most bang for your buck using preload for resources that might be discovered much later. An example of this could be a specific font tucked deep in one of your CSS files.

Style sheet and JavaScript files are not the only types of resources we can pre-emptively fetch using preload. Other types of content can be preloaded as well.

Link Prefetch

Instead of preload, we can also make use of a prefetch tag for some of our resources. The difference here is that prefetch is more suited for resources needed for a different navigation route. This means that the browser will know to fetch and cache this resource once it has completed loading the current page.

Although it may seem straightforward to add <link rel="preload"> and <link rel="prefetch"> tags to the head of your HTML document for static sites, it can be a little tricker if you happen to be using a module bundler for a single-page application. Fortunately, there are a number of potential tools that can make this easier:

webpack 4.6.0 provides support for prefetching and preloading resources using ‘magic’ comments:

import(/* webpackPreload: true */ "PreloadedPage")

import(/* webpackPrefetch: true */ "PrefetchedPage")

If you happen to be using an older version of webpack:
- preload-webpack-plugin is a webpack plugin that allows you to define dynamically generated chunks (as a result of code-splitting) as preloaded or prefetched resources. This plugin is supposed to be used alongside html-webpack-plugin.
- script-ext-html-webpack-plugin is an extension of html-webpack-plugin and can be used to attach custom attributes and resource hints to generated chunks, including preload and prefetch.

Browser Support

At the time of writing this article, the browser support for preload is as follows:

Shipped:
- Chrome
- Safari
- Firefox
In development:
- Edge

HTTP/2 Server Push

We’ve just covered how we can use <link rel="preload"> to load critical resources as early as possible, but another useful point of topic is HTTP/2 Server Push. In short, HTTP/2 is a revision of HTTP and aims to provide a number of performance improvements. For the purpose of this article, we’re only going to focus on Server Push.

The idea behind Server Push is that when we send down the initial HTML document during our first request/response interaction, we can also send down (or push) critical assets at the same time. These are assets we know the browser will need before it even knows it needs them itself.

One of the primary benefits of using Server Push is that it can minimize round trips to the server. We can remove the time it takes the browser to parse the contents of the HTML file and fire subsequent requests for any assets that it finds which can result in shorter page load times.

One thing we didn’t mention earlier about preload is that instead of using HTML tags, we can also specify HTTP headers:

Link: </app/style.css>; rel=preload; as=style
Link: </app/script.js>; rel=preload; as=script

Many hosting platforms that support HTTP/2 Push will attempt to push assets down the wire when it sees that you’ve preloaded them using Link HTTP headers. Examples include Firebase Hosting and Netlify.

Although having Server Push instantiated automatically for assets where we've declated Link Headers can be useful, there may be cases where you may only want to preload your assets and not rely on Push whatsoever. In those cases, you can use a nopush attribute:

Link: </app/style.css>; rel=preload; as=style; nopush
Link: </app/script.js>; rel=preload; as=script

The result here is the same as using a preload link HTML tag.

Server Push is experimental

Although page load times can be reduced with Server Push, it can actually harm performance if not used correctly. There are a number of reasons why this can happen:

Pushing unused assets: The server has no idea which resources are being used by the client, and pushing assets that aren’t used can waste user bandwidth.
Pushing too many assets: Pushing too many assets can cause performance hits. There’s no specific number of files you should be pushing and it can vary depending on how many resources the browser is trying to load. It is important to keep in mind that Server Push can overwrite the browser’s prioritization logic and you should try pushing assets with the correct order of loading.
Pushing assets already cached by the browser: Ideally, we would want the browser to reject pushed resources if it already has it stored in one of its caches. Although the client can use settings to make this possible, each browser behaves differently and this can get a little tricky. Jake Archibald covers this in a little more detail in his excellent write-up about the nuances of HTTP/2 Push between different browsers.

Service Workers

Now let’s shift gears a bit and talk about the pre-cache concept in PRPL. I’ve briefly addressed service workers in my previous post about building progressive Angular applications, but we’ll dive a little deeper here.

A service worker is a script that runs in the background of your browser when you view a webpage. We can either create the service worker file and write the logic ourselves, or we can use libraries that can make this process easier. One example is Workbox, which provides a suite of libraries and tools that we can use. One of the tools that it provides is a CLI which we can install globally:

npm install workbox-cli --global

We can run workbox wizard in our terminal to start the process. Workbox will then ask a series of questions in order to set up a service worker with the correct configurations:

What is the root of your web app? If you’re using a module bundler or have a build step in your application, you most likely have a final folder that you’ll need to deploy (for example: dist/ or build/).
Which file types would you like to precache? You can decide which file types you would like to precache.
Where would you like your service worker file to be saved? You most likely would need to have your service worker saved in the folder you deploy, but you can specify where exactly.
Where would you like to save these configuration settings? Workbox saves these settings into a separate configurations file (and you can decide where to save it).

The default answer for saving the configurations file is workbox-config.js at the root of your application. The generated file looks like this:

module.exports = {
  globDirectory: 'dist/',
  globPatterns: ['**/*.{js,png,svg,html,json}'],
  swDest: 'dist/service-worker.js',
};

Once we have our configurations file saved, simply running the following command creates a new service worker file:

workbox generateSW workbox-config.js

Although this creates a service worker file where we’ve asked it to, we still need to tell the browser to register it. We can do this by adding a <script> tag in index.html:

<script>
  if ('serviceWorker' in navigator) {
    window.addEventListener('load', function () {
      navigator.serviceWorker.register('/service-worker.js').then(function(){
        // Registration was successful
        console.log('ServiceWorker registration successful!');
      }).catch(function(err) {
        // registration failed :(
        console.log('ServiceWorker registration failed: ', err);
      });
    });
  }
</script>

In here, we check to see if service workers are supported in the browser. If they are, we register our service worker using navigator.serviceWorker.register(). To prevent the possibility of the service worker being registered at the same time as other resources are still being loaded to the DOM, we make sure to only register it after window.onload is complete with the use of an event listener. At the end, we have logs outputted to our console in the case of a successful registration or a failed one.

Application Shell

So we briefly covered how to install and register a service worker using Workbox, but we still haven’t mentioned how they work. One of the primary benefits of using a service worker is that they allow you to precache the resources that make up the Application Shell. Like the name suggests, the App Shell is the shell of your user interface.

Application Shell - Twitter Lite

The App Shell consists of all the HTML, CSS and JS that make up the parts of that application that don’t convey actual data (or dynamic data retrieved from a third-party location). Once the app is loaded for the first time, the assets that make up the shell can be retrieved over the network normally. A service worker can act like a middleman between the browser and the network allowing us to to cache these resources as well.

Storing the resources that make up the shell in the service worker cache means that when the user loads the application for a second time, the browser can retrieve them from the service worker instead of making network requests. This results in faster page loads on repeat visits.

Although using Workbox’s CLI can simplify creating a service worker, we would still need to remember to create a new one every time we make a change to our application. In this case, it might make more sense to integrate Workbox into our build system. For example, instead of installing the library globally - we can install it as a dependency:

npm install workbox-cli --save-dev

We can then add it as part of our build step:

// package.json

"scripts": { 
  //...
  "build": "{build} && workbox generateSW workbox-config.js" 
}

Dynamic Content

The next thing service workers allow us to do is pre-cache dynamic content. Just like the resources that make up the App Shell, this is data that can be retrieved from a third-party network. However, the difference here is that this is content that can change with subsequent page loads.

Let’s modify our configurations file, workbox-config.js, to add a runtimeCaching attribute:

module.exports = {
  globDirectory: 'dist/',
  globPatterns: ['**/*.{js,png,svg,html,json}'],
  swDest: 'dist/service-worker.js',
  runtimeCaching: [
    {
      urlPattern: /^https:\/\/your.api.com\/.*/,
      handler: 'networkFirst'
    }
  ]
};

With runtimeCaching, we can add an array of URL patterns and define a specific caching strategy for each. Different caching strategies allow us to control how our service worker can handle caching results fetched from a URL. In this example, we use the networkFirst strategy which means the service worker will always know to retrieve the contents from the network and serve it to the user. However, it will also always update its pre-cached results with the latest data. If the network happens to fail, the service worker will serve its cached information and the user can see older data instead of no data at all.

Although extremely useful for applications where data is changing frequently, networkFirst isn’t the only caching strategy we can use. Let’s quickly go over the others:

cacheFirst: If there is no cached data, a network request is made and the results are cached. After that, the cache will only serve its data and no network requests will be made. This can be useful for handling things in an offline-first manner.
staleWhileRevalidate: Mostly suited for serving non-critical data to the user as fast as possible, this approach is used to serve cached data to the user quickly at first. A network request is also made in parallel with the request made to the cache. When the network request is complete, the cache is updated.
cacheOnly: Only retrieve resources from the cache and do not rely on the network at all. However, cacheFirst is more commonly used for offline-first patterns.
networkOnly: Only retrieve resources from the network and do not have any data cached. This may not be commonly used but may be suitable for data that cannot be cached.

Customize Service Worker

Although using the Workbox CLI can make getting a service worker up and running an extremely simple and straightforward process, there may be scenarios where we would need a little more control on how our service worker is created. This can be for a number of reasons:

We have more complex pre-caching requirements than what Workbox provides out of the box.
We want to take advantage of other service worker features (such as Web Push)
We already have a service worker file and only need to incorporate some Workbox features in addition to it.

For any of these scenarios, we can use the injectManifest mode provided by Workbox:

workbox injectManifest workbox-config.js

By using this flag, we not only need to provide a destination service worker location but the location of an existing service worker as a source as well.

Browser Support

At the time of writing, service workers are supported in all major browsers:

Shipped:
- Chrome
- Safari
- Firefox
- Edge

Bundles

Front-end development has changed a lot in the past few years. A large number of JavaScript libraries and frameworks have allowed us to add more client-side logic and functionality than ever before. Unfortunately, this can come at a cost of larger bundle sizes.

Although adding more and more JavaScript code to a large application will inevitably make our bundle sizes grow and grow, we can incorporate code splitting into our application to help. The idea behind code splitting is that instead of providing users with all of the code that makes up our application as soon as they navigate to the first page, we can try to give them pieces of the entire bundle that are only relevant to their current route. The browser can then make requests for more chunks of the bundle as the user navigates through the application. The concept of loading different pieces of a bundle on demand is called lazy loading.

Code splitting and lazy loading allow us to send smaller chunks to our users as well prioritize loading of specific chunks if we need to (with <link rel="preload"> for example). This can improve loading times significantly.

Angular’s routing framework has lazy loading built-in where we can use a loadChildren attribute to load a feature module on demand:

export const routes: Routes = [
  { path: '', redirectTo: 'main', pathMatch: 'full' },
  { path: 'main', component: MainComponent },
  { path: 'details', loadChildren: 'details/details.module#DetailsModule' }
];

For React, React Loadable is an excellent library that allows you to create higher order components to load components asynchronously.

// snippet from React Loadable README.md

import Loadable from 'react-loadable';
import Loading from './my-loading-component';

const LoadableComponent = Loadable({
  loader: () => import('./my-component'),
  loading: Loading,
});

export default class App extends React.Component {
  render() {
    return <LoadableComponent/>;
  }
}

Code splitting at the component level can even allow for more fine-grained control over doing things at the route level.

There are many more places than just routes where you can pretty easily split apart your app. Modals, tabs, and many more UI components hide content until the user has done something to reveal it.

React Loadable README.md

Tracking bundle size changes

If you’re considering adding code splitting/lazy loading to your application, it’s probably a good idea to keep an eye on your bundle size from time to time. There are a number of different community-built tools that can make this easier, such as Webpack Bundle Analyzer which shows a visualization of how different parts of your bundle are larger/smaller than others with a treemap.

Metrics

With regards to load times, using metrics can be important to set a baseline on how well our webpage loads for different users. Some important metrics to consider are:

First Meaningful Paint: The time it takes the user to see meaningful content on their device.
Time to Interactive (TTI): The time it takes for the JavaScript thread to settle and the user can interact with the application.

As developers, many of us have become accustomed to building web applications with healthy network connections and powerful machines. At times, we may not realize how users would experience our applications with lower-end devices and weaker connections. According to a Google Research statistic, the average time it takes to fully load a webpage on mobile is greater than 20 seconds. This was found by running tests on a globally representative 3G network connection and a Nexus 5 device. Another Google Research statistic found the average load time to be 15.3 seconds with a 4G connection.

If a webpage takes longer than 3 seconds to load, more than half of our users will give up.

Conclusion

It’s important to first spend a little time analyzing the devices of our users before adding performance enhancements that very well may not be necessary (or important as other features our application needs). If we find out our application is not loading as fast as it probably should after a little digging, then it may be worthwhile to dive in and try adding some optimizations!

Looking back at 2017

Fri, 05 Jan 2018 07:30:00 +0000

I’m late, I know.

Let’s take a look at what I accomplished this past year:

Joined Rangle.io
Published two books (one still in progress) with the amazing folks at Fullstack.io.
Spoke at 5 conferences around the world plus a dozen more meet-ups and events.
Travelled to more cities in a single year than the previous ten years combined (I visited Europe for the first time!).
My blog garnered over 100,000 page views (even though I haven’t published a new post in almost a year :O).
Built GitPoint, which currently has over 11,000 users.
Built Angular HN which was briefly featured at Google I/O (a million thanks to Addy for all the help and advice I needed to build this app).
Helped build HNPWA and Essential Image Optimization
Started investing in different cryptocurrencies along with a squad. We’re all either making stupid decisions or smart choices, but we’re doing it together.
Worked with some amazing developers on open source that have taught me more than I ever thought possible.

Now let’s talk about the other side of things:

Imposter syndrome is my good friend seven days of the week.
Haven’t learned any other languages besides JavaScript.
Get nervous every single time I give a talk. Don’t think that’ll change anytime soon.
With kind of a non-traditional path to web development, I‘m (still) not confident with basic computer science fundamentals.
I’ve only scratched the surface with things in the JavaScript ecosystem.
I’ve focused on front-end and my back-end experience is severely lacking.
I have over a dozen half baked side projects and there are literally only two side projects I’ve ever built to completion (not including other people’s projects I’ve helped). That’s still two more than last year, so there’s that!
Still a complete noob at almost everything I do.
I’m still trying to find the right balance of things. I’ve been stressed more than a few times, and I don’t want to burn out.
Still haven’t learned how to swim or skateboard (properly). THESE TWO ARE THE MOST IMPORTANT THINGS I NEED TO LEARN THIS YEAR FAM.

Looking further back

Since this is my first time writing a “year in review”, let’s look further back a bit:

This time last year, I was just getting into the groove of building a web app. I’ve never given a talk before and have always thought a beginner like me couldn’t come close to speaking on stage.
This time two years ago, I had never written a line of JavaScript.
This time three years ago, I was (wrongly) confident that coding just wasn’t for me and avoided it like the plague.

I submitted my first pull request to open source a year and a half ago. If it wasn’t for the amazing welcoming attitude of those reviewers (thanks Kent :)), I probably wouldn’t be nearly as excited to contribute to open source as much as I am now.

Goals for 2018

New Years resolutions never made sense to me. Why not just begin something in December if it’s weighing on your mind? Why wait for the new year?

With that being said, I think we all have things we want to improve on. If somebody likes to plan goals on a yearly basis, who am I to say that’s not the right of way of doing things. There really isn’t a “correct” way to have goals.

So what about myself? Sure, I can say I want to work on more open source projects, give more talks, write more technical content and so on. Will I get disappointed if I don’t do anymore of these in 2018? Maybe. But there’s more important things to think about.

One thing I regret about spending quite a bit of time on stuff like this outside of my full-time job is that I’ve not nearly helped as many people get into web development that I would have liked to. Every week, I meet individuals who were pretty much in the exact same shoes I was two years ago - unsure about what web/mobile development really is but curious enough to start trying to get involved. And I’m not talking about JavaScript enthusiasts in particular, this includes folks interested in design, DevOps, user experience, marketing and so on.

So for 2018, if I focus too much on myself and not help as many newcomers that I can get into the intimidating world of web development — hold me accountable.

Progressive Web Apps with Angular

Tue, 17 Jan 2017 07:30:00 +0000

Progressive Web Apps (PWA) have been the talk of the town in 2016. In short, they are applications that use modern web capabilities to provide a user experience similar to that of mobile and native apps. Still a relatively new concept, these applications work for every user in every browser but are enhanced in some.

An earlier post of mine (see here) revolved around building a Hacker News client from scratch using Angular CLI. In this post, we’re going to look into how we can make it faster and more reliable by making it a PWA.

View App Source Code

Let’s go through some of the main concepts of progressive applications.

They are progressive, meaning that they work for every user in every browser
Although they may provide a mobile-like experience, they are responsive and work on every device and screen size
Push notifications and offline support are both features that can be included
They can be installed to the home screen of your device
They can be accessed directly with just a URL

The case for Progressive Web

XKCD - Installing

Although installing an app is usually a fast and simple process, when was the last time you were about to install something but decided not to? Maybe you felt like you didn’t want to go through the hassle of installing it, or maybe you just didn’t want use to up any more memory. Whatever the reason, almost every single mobile user has experienced this at some point.

However, most people feel a lot less restricted to open up a browser and just type in to the address bar. The convenience, security and simplicity of just typing a URL into an address bar is a powerful advantage of the web, and PWAs combine this with the feel of native applications.

Lighthouse

Lighthouse is an open-source auditing tool that you can use to test and improve your webpage. It runs a number of tests and generates a report on how well the page did. You can install Lighthouse as a Chrome extension or use its Node CLI tool.

Here’s a snippet of the report before I added a number of progressive elements to the app.

The report consists of a number of audits that validate the aspects of a PWA. Let’s go over each of these audits and how we can improve each of these areas in our application.

Note: This tutorial will reference my Hacker News client as we add a number of different tools to improve it. However, you can easily follow along and include each tool in your app if you already have an application built with Angular CLI. If you don’t and would like to know how, my previous post can help.

Network connection is secure

A number of progressive web technologies, such as service workers (which we’ll go over in a bit), require a HTTPS connection in order to work. The ‘S’ at the end, which stands for secure, ensures that the content that you retrieve is secure and cannot be tampered with.

There are a number of hosting platforms that are protected with HTTPS by default which makes it easy to have your website or application protected. Our Hacker News client is hosted on Firebase and this website is hosted on Github Pages: both allow HTTPS encryption.

I also wrote a post that explains how you can deploy your Angular CLI app with Firebase so please take a look if you’re interested.

Page load performance is fast

Let’s take a look at how our app loads without any configuration. To represent mobile users more fairly, we’ll use simulated conditions of a 3G Network and a CPU Throttle of 2X slower thanks to Chrome’s Developer Tools.

Humans are impatient creatures, and 53% of us will give up if a site takes longer than 3 seconds to load. Even under these simulated conditions, no webpage should take this long to load if we can prevent it.

Ahead-of-Time compilation

Components, along with their HTML templates, are the foundation of any Angular application. By default, this is all converted into viable JavaScript when you run the application in the browser. In other words, compilation happens Just-in-Time.

One way we can make an Angular app load faster is to run its compiler under Ahead-of-Time conditions. This means that the compiler only runs once during the build step. The app does not have to compile when you try to load it in the browser.

With Angular CLI, creating a production build is as simple as a terminal command.

ng build --prod

Creating a production build with AOT compilation is also just as simple (this really goes to show the amazing work the CLI team has done to make our lives easier).

ng build --prod --aot

And that’s it. Now let’s see how our app loads under the same conditions.

The app now loads 55% faster. That’s a pretty big difference for such a quick adjustment. The bundled file sizes were also reduced by roughly 40%.

Note: If you would like to understand how AOT works in more detail, Juri does an awesome job explaining it in this screencast.

Application Shell

An application shell (or App Shell) is the minimal HTML, CSS and JS responsible for providing the user with the shell of the user interface. A toolbar is a good example of something that would be encapsulated in this shell. In a PWA, the App Shell can be cached so it loads as quickly as possible when a user decides to return to the webpage. With this, we can provide the user with something meaningful immediately even if the actual content has not rendered yet.

We can see that the App Shell in this application just consists of a header, navigation and loading icon that shows while the content is being fetched over the network. To cache our shell in order to load faster on repeat visits, we’ll need to add a Service Worker to our application.

Service Worker

A service worker is a script that runs in the background of your browser when you view a webpage. It is entirely separate from the webpage itself and can only communicate with it.

We can register a service worker to our application by adding the following to index.html.

<script>
  if ('serviceWorker' in navigator) {
    navigator.serviceWorker.register('/service-worker.js').then(function(registration) {
      // Registration was successful
      console.log('ServiceWorker registration successful with scope: ', registration.scope);
    }).catch(function(err) {
      // registration failed :(
      console.log('ServiceWorker registration failed: ', err);
    });
  }
</script>

All this does is check to see if the browser supports service workers and if so, register it’s file path. Let’s run our application locally with ng serve or ng serve --prod, open it in a Chromium browser (Google Chrome, Firefox or Opera) and check the console.

We can see that it can’t retrieve the service worker file, service-worker.js, since it doesn’t exist. There’s a few ways we can set up this file:

Create the file and write out the logic to open a cache, cache all the static files (HTML, CSS, JS, images, etc..) and return the cached resources when the user returns to the page. Here’s an excellent introduction to setting up a service worker.
Use Service Worker Precache.

Service Worker Precache

Service Worker Precache (sw-precache) is a module that generates a service worker responsible for caching all the static resources in your application. It integrates right into the build system you’re using and, with some simple configurations, creates the service worker on the fly. We can begin by installing its package.

npm install --save-dev sw-precache

Now in your package.json file, let’s add a precache script that runs a simple command: sw-precache.

"scripts": {
  "ng": "ng",
  "start": "ng serve",
  "lint": "tslint \"src/**/*.ts\"",
  "test": "ng test",
  "pree2e": "webdriver-manager update --standalone false --gecko false",
  "e2e": "protractor",
  "precache": "sw-precache"
}

Now just run the following script.

npm run precache

It generates a service-worker.js file right in your root folder. You can see the output also includes the total size and number of assets that are cached. This corresponds to the total number of resources that your application shell contains.

Furthermore, if you take a look at the actual file, you’ll see logic that installs and activates your service worker. You can also find where it caches and returns requests (fetch event).

Now this is all pretty cool and everything, but having the service worker in the root of our application isn’t going to help us. This is because when you run a production build with the CLI (ng build --prod or ng build --prod --aot), it generates the compiled, bundled and minifed code in a dist/ subdirectory which we deploy and host. We can update our precache script to make this happen.

"scripts": {
  // ...
  "precache": "sw-precache --root=dist --verbose"
}

Now running the script should generate the service worker right inside the dist/ directory. We’ve added verbose so we can see a logged output in the terminal for each and every resource that’s precached. Let’s run ng build --prod --aot to set up a production build followed with npm run precache.

We can see that our service worker file was generated in the dist/ folder which is perfect. We can also see that each and every static resource in our dist folder is precached by default. This is a bit overkill since not every one of those files are requested when you run the application. Now if we wanted to just precache our HTML files, we can use the following command instead.

"scripts": {
  // ...
  "precache": "sw-precache --root=dist --verbose --static-file-globs='dist/**.html'"
}

We’re adding quite a bit to our script now. To make things simpler, we can set up a separate file to specify what configurations we would like for our service worker. Let’s create a sw-precache-config.js file right at the root of our application and move our current configurations there.

module.exports = {
  staticFileGlobs: [
    'dist/**.html',
  ],
  root: 'dist'
};

We can now simplify our script to just refer to that file.

"scripts": {
  // ...
  "precache": "sw-precache --verbose --config=sw-precache-config.js"
}

Now let’s run npm run precache once more.

As expected, the only HTML file in our production folder, index.html, is cached. Remember that Angular is a Single Page Application, where the final output consists of a single HTML file that dynamically changes based on the JavaScript we have. Now that we have a decent understanding of how sw-precache allows us to set up a service worker, let’s add some more configurations to sw-precache-config.js.

module.exports = {
  staticFileGlobs: [
    'dist/**.html',
    'dist/**.js',
    'dist/**.css',
    'dist/assets/images/*',
    'dist/assets/icons/*'
  ],
  root: 'dist',
  stripPrefix: 'dist/',
  navigateFallback: '/index.html'
};

We can precache all our static files (HTML, JS and CSS) along with our assets folder which contains our icons and images (we’ll go over generating icons for our application in a bit)
Since our built app lives solely in the dist folder, we use stripPrefix to remove it from the beginning of any file paths that may be referenced
When the app attempts to fetch a request not found in the cache, we use navigateFallback to set index.html as our fallback (couldn’t think of another word :P)

Now that we have all our static resources set up for precaching, we need to make sure to generate our service worker right before we deploy the app to our hosting platform. For example, if we were hosting our application on Firebase, we would do the following:

ng build --prod --aot
npm run precache
firebase deploy

Once deployed, let’s take a look at the network requests when we load the application on a repeat visit.

You can see that every precached resource was retrieved from the service worker! The only data transferred was our third party call to get the list of stories from the Hacker News API. Let’s take a look at the captured sequences on reload.

Not bad at all. You can see that the static resources load a lot faster since they’re now being retrieved from the service worker. This significantly reduces our Time to Interactive.

Service Worker Webpack Plugin

To make this entire procedure a lot simple, there’s a Webpack plugin for service workers, SWPrecacheWebpackPlugin, that you can include in your Webpack configuration. When I built this application, Angular CLI did not support overriding Webpack configurations. However, the team has recently included the ability to eject and modify your configurations so using this plugin may probably make things even smoother (and I look forward to trying this soon).

Continuous Integration

It’s important to remember that because we’re doing this manually, we need to make sure we generate our service worker every time we create a new build. For example, this app is hosted on Firebase and I use a simple command line, firebase deploy to host dist/. So that means I need to always run the following in order when I make updates to my app.

ng build --prod --aot
npm run precache
firebase deploy

There’s been quite a few times I forgot to run that command, so I set up a simple continuous integration script that automatically runs a build, generates a new service worker and deploys to Firebase every time I just push to my repository. My previous post explains how I set this up as well.

App can load on offline/flaky connections

Now that we understand how we can set up an App Shell using sw-precache, let’s look at another important factor of progressive web applications, working with unavailable or poor network connections. We’ll be using another library for this, Service Worker Toolbox (sw-toolbox).

Although this is a different tool, sw-precache is capable of including this just by adding a new configuration, runtimeCaching, to our config file. Although this may change in the future, this lets us easily integrate dynamic network caching into our service worker.

We wanted to make it easier for developers to use the two libraries together. Because sw-precache has to be directly integrated with your build environment and must be responsible for outputting your top-level service worker file, it made the most sense as an integration point to give sw-precache the ability to include the sw-toolbox code and configuration alongside its own configuration.

sw-precache? sw-toolbox? What's the difference?

runtimeCaching

Let’s look at how we can add this configuration to sw-precache-config.

runtimeCaching: [{
  urlPattern: /node-hnapi\.herokuapp\.com/,
  handler: 'networkFirst'
}]

And that’s pretty much all I needed to do for my application. The configuration consists of an array with each object referencing a separate urlPattern. You can see that I have a RegExp here referencing the unofficial API I’m using to power my application. You can also use a string among other route types (the docs give a clear overview of the different route styles you can use).

handler is also required and you can see that I’m using networkFirst. There are a total of five built-in handlers that allow you to modify your network strategy. For networkFirst, the toolbox will try to handle the request first by retrieving from the network and if that succeeds, it will cache the response. When this fails (flaky/unavailable network), it will fetch directly from the cache.

The documentation also explains the different handler types clearly. To get a better understanding of each of the network strategies, The Offline Cookbook is an excellent read.

Now when we run the application offline, requests previously fetched are now retrieved from the cache. This means that the user can now use the app with pages they have previously visited.

Someone was nice enough to open an issue and mention that for failing requests (both cache and network), it makes more sense to show an error message instead of a loading indicator. Consider the following two scenarios:

The API fails through the network and is not cached (first-time viewing that page)
The API works, however the user is offline but navigates to a page that they have not yet visited

In either of these scenarios, an appropriate warning message would be nice so the user isn’t confused when nothing is loading, especially on a mobile device.

Awesome minimalist skull CSS by Max on Codepen

Site is progressively enhanced

One of the primary principles behind progressively enhanced web pages is that anyone and everyone should be able to access its basic content at the very least. So far we’ve overlooked those who browse the web with JavaScript disabled.

Working without JavaScript

Some think that always developing an application for users with their JavaScript disabled doesn’t make much sense. If you think about it, SPA’s rely on client JS in order to work. That’s how we end up with a single index.html file that dynamically changes based on user events.

But how would we go about having a SPA to work without client side JS in the first place? We can do this by server-side rendering some (or all) of our content. Angular Universal allows us to do this in Angular applications, which can give your application a better perceived performance and make it more SEO friendly.

I haven’t had the chance to try this (and hopefully I will soon), but in the meantime we can at least insert a <noscript> tag in index.html to warn the user that JavaScript is required.

Design is mobile-friendly

If you plan on building a web application and not expect any users to access it through their mobile device, than you may not be concerned with how it looks with smaller screens whatsoever. However, more and more users access the web through their phones and if you intend on building an app with progressive enhancement in mind, you most likely want to make sure it sizes correctly to all screen sizes.

In this area, Lighthouse will check to see if your HTML has a <meta name="viewport"> in order to optimize your app for mobile devices. Fortunately, Angular CLI includes this by default.

<meta name="viewport" content="width=device-width, initial-scale=1">

User can be prompted to Add to Homescreen

We can give users the ability to install the application to their homescreen in order to feel more like a native application.

This is done by adding a Web App Manifest, a JSON file that contains specific information about your app. We can begin by adding a link to the head of our index.html.

<link rel="manifest" href="/manifest.json">

Since we need this file as we build our app into the dist directory, we’ll need to add it as an asset in angular-cli.json.

"assets": [
  "assets",
  "favicon.ico",
  "manifest.json"
]

Now let’s create manifest.json in our src folder.

{
  "name": "Angular 2 HN",
  "short_name": "Angular 2 HN",
  "icons": [
    {
      "src": "assets/icons/android-chrome-192x192.png",
      "sizes": "192x192",
      "type": "image\/png"
    }
  ],
  "display": "standalone",
  "start_url": "./?utm_source=web_app_manifest"
}

Many of these configurations are self explanatory, but this resource from MDN does a great job explaining each one.

Since our manifest has a short_name, a start_url and an icon larger than 144px, our application will show an install banner to prompt the user to install the app to their home page. This banner shows if the user visits your site at least twice with five minutes between each visit.

Installed web app will launch with custom splash screen

Another thing that a manifest file allows for is a custom splash screen when you open the app through your home screen. This is useful because it can reduce the perceived load time of your application (even if it loads in the same amount of time). To do this, we’ll need to flush out our manifest file a little more.

{
  "name": "Angular 2 HN",
  "short_name": "Angular 2 HN",
  "icons": [
    {
      "src": "assets/icons/android-chrome-192x192.png",
      "sizes": "192x192",
      "type": "image\/png"
    },
    {
      "src": "assets/icons/android-chrome-256x256.png",
      "sizes": "256x256",
      "type": "image\/png"
    }
  ],
  "theme_color": "#b92b27",
  "background_color": "#ffffff",
  "display": "standalone",
  "orientation": "portrait",
  "start_url": "./?utm_source=web_app_manifest"
}

You can see that we’ve added two new attributes, theme_color and background_color. The manifest needs to contain this along with name and an icon of at least 192px (we added a new one of 256px) in order to serve a splash screen.

Icons

To simply generate a number of icons needed not just for Android, but for Windows and iOS devices as well, I used RealFaviconGenerator. It shows you how your icons will look in each device as well previews of the splash screen in Android. It then provides the markup you can include in your index.html along with all the icons you need (which I put in assets/icons).

Installing with iOS

Like Chromium browsers (Chrome, Firefox, Opera) on Android, Safari on iOS allows you to install to homescreen and provide an icon. However, splash screens are not supported.

Moreover, with the presence of a web manifest, the URL bar is automatically removed giving the user a full-screen experience on Android devices. This is not the case on iOS, but there are supported meta tags that we can add to fix this (credits to Bram Borggreve, I didn’t know this was possible until he put up a PR for this!). With this, we can have a rich full-screen experience on iOS as well.

Recording by Bram Borggreve

Best Practices

Along with audits that measure the aspects of a PWA, Lighthouse provides a list of recommendations to improve your webpage in terms of best practices. Although these don’t affect your score, it’s still fun/handy to tick them off the list as you work on your application. Some examples:

Site opens external links using rel="noopener"
Every image element has an alt attribute

Conclusion

Although Angular Mobile Toolkit may eventually make creating a PWA a smooth and simple process with the CLI, it’s still very possible to integrate a number of progressive elements to your application without adding much overhead at all.

I hope this tutorial helped you and if it did, please tweet it forward and star the repo! You can also follow me on Twitter if you haven’t had enough of me rambling.

Continuous Integration | Angular CLI + Firebase + Travis CI

Sat, 07 Jan 2017 07:30:00 +0000

After completing the first step of building your application, the next thing most of us do is pick a hosting platform (like Github Pages) and deploy it. This is awesome, but we always need to make sure to deploy a newer build every time we update our app. We also need to run any unit tests we may have and make sure they pass beforehand.

Thankfully, there are continuous integration and deployment tools that can make this process a lot simpler. This isn’t something you only need to do for large scale production applications, but even updating a small hobby project can be a lot easier if all you had to do is push to your repository and let your integration pipeline do the rest.

The breakdown

In this post, we’ll begin by creating an application from scratch using Angular CLI. We’ll then use Firebase as our hosting service and Travis CI as our continuous integration platform. By the end of this article, your workflow will look something like this:

You push to your Github repository
Grab a coffee
TravisCI begins by installing all the dependencies
The build script is run
If your build passes, the application is deployed to Firebase

This post will not explain how you can use the CLI in detail nor show you how to actually build an Angular application. I wrote a post that explains this thoroughly so please take a look if you’re interested.

Getting Started

Let’s start by installing Angular CLI.

npm install -g @angular/cli

And now we can create and run a new project. I’m going to call it Boom Shakalaka.

ng new boom-shakalaka
cd boom-shakalaka
ng serve

If you go to localhost:4200, you’ll see your application!

Since Travis CI easily syncs with Github, let’s create our repository.

We can now add the remote repository to our project.

git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/YOUR_USERNAME/boom-shakalaka.git
git push -u origin master

Firebase

Firebase is an awesome platform that provides a number of different services that you can you use for your mobile or web application. There are two that I use quite often, the database as well as the hosting platform.

For Boom Shakalaka, we’ll only need to host it. We can do that by using the Firebase CLI, but first you’ll need to sign in, head to the console and create your project.

Once you’ve created your project, you can head to your terminal and run the following at the root of your project to set up the CLI.

npm install -g firebase-tools
firebase login
firebase init

You should see the following in your terminal.

Let’s go through each of the questions.

What Firebase CLI features do you want to setup for this folder? – Hosting
If it asks you which Firebase project do you want to associate as default, select the correct project
What file should be used for Database Rules? – Just click enter since we’ll not be using the database for our application
What do you want to use as your public directory? – Type in dist and hit enter (this is because when you run a build with Angular CLI, the compiled code that should be deployed is located in this directory)
Configure as a single-page app? – Yep

And that’s it. Since you specified your default project, all you’ll need to do is run the following to create a production build and deploy it.

ng build --prod
firebase deploy

Now if you navigate to the URL provided, you’ll see your application!

In your terminal, run the following command to get your token (you’ll be asked to authenticate). We’ll need it in a bit.

firebase login:ci

Travis CI

Travis CI is a continuous integration platform that you can use with your Github projects. Once synced with your repository, it will build the project and run your tests every time you push to your branch (or merge a pull request).

Check the one you wish to sync and click the little cog icon to enter its settings.

You can see that I have Build Pushes and Build Pull Requests turned ON. This means that anytime I push directly to this repository or merge a pull-request, Travis CI will trigger a build.

You also need to add an environment variable for your token. Let’s name it FIREBASE_TOKEN and copy the token we just generated in our terminal.

Now the final thing we need to do is set up our configurations, which we can do by creating a .travis.yml file at the root of our project (notice how I also have Build only if .travis.yml is present turned ON).

#.travis.yml

language: node_js
node_js:
  - "6.9"

branches:
  only:
    - master

before_script:
  - npm install -g firebase-tools
  - npm install -g @angular/cli

script:
  - ng build --prod

after_success:
  - firebase deploy --token $FIREBASE_TOKEN

notifications:
  email:
    on_failure: change
    on_success: change

The docs do a great job explaining the build lifecycle, but I’ll quickly summarize these configurations.

before_script: These are commands that run before the build step. Here I just install firebase-tools and angular-cli.

script: The build step where we run a production build for our application.

If you needed to, you can have multiple commands here and they will fire in order. A good example would be generating a service worker after every build.

after_success: These are additional commands that run if the build succeeds. In our case, we just deploy to Firebase.

If you have multiple Firebase projects/aliases set up, you can specify firebase use YOUR_PROJECT_ALIAS before the deploy command to specify which project you want to deploy.

notifications: You can specify the type of notifications you would like and when to receive them. More info in the docs.

Unit tests

I didn’t cover tests in my configuration, but it is important to mention that Angular CLI uses Karma for it’s unit tests which run against a browser. Here’s a great article that explains how to setup your configurations to have Travis CI run unit tests on Google Chrome. Here’s another article that shows how you can have your unit and end-to-end tests run as part of your build for your Angular CLI project.

Triggering a build

Now that we have our .travis.yml file set up, I’m going to modify the application slightly to look like this.

Now all we need to do is commit and push our changes.

git add .
git commit -m "set up .travis.yml"
git push origin master

And that’s it! You can always take a look at your build status on your repository in Travis CI. After a few minutes, you should see your newly built application deployed. You can see mine here.

Conclusion

If you were looking to find a simple way to set up an Angular project with continuous integration, then I hope this helped . As always, please don’t hesitate to let me know if you have any questions or feedback!

Building Hacker News with Angular 2 CLI, RxJS and Webpack

Fri, 16 Sep 2016 13:20:00 +0000

If you have ever built an Angular 2 application before, you’ll know that setting up and bootstrapping an application can take a significant amount of time. Thankfully, the Angular team have rolled out Angular CLI, a command line interface that makes creating and scaffolding an application significantly easier.

In this post, we’ll build an entire Hacker News client using Angular CLI, RxJS Observables and Webpack as our module loader.

View App Source Code

We’ll go through building the entire application step by step. Throughout this post, I’ll try my best to explain my thought process as well as some of the mistakes I’ve made and what I did to fix them.

Here’s a rundown of what we’ll be doing.

We’ll start by building our basic setup first, the front page of Hacker News
We’ll then wrap an Observable Data Service to load data asynchronously
To allow the user to navigate between different pages and story types, we’ll add routing using the Angular Component Router
Finally, we’ll add routes to allow the user to navigate to item comments and user profiles.

This visual tutorial should make you feel a little more comfortable building an Angular 2 application from small modular parts as well as creating an app from scratch all the way to completion. We’ll also briefly go over some important topics and understand how they apply to an actual application, which includes:

The NgModule decorator
View Encapsulation
RxJS

Getting Started

Once you have the required Node and NPM versions, you can install the CLI through your terminal.

npm install -g @angular/cli

You can then create and start your application.

ng new angular2-hn
cd angular2-hn
ng serve

If you now open https://localhost:4200/, you’ll see the application running.

Pretty cool huh? Angular CLI used to use SystemJS as the module bundler and loader. Using SystemJS had a few quirks including long loading times and a lengthy process just to add third party libraries. So to make things simpler and faster, the Angular CLI team have moved from SystemJS to Webpack!

NgModule

Bootstrapping an application with CLI uses Angular’s latest release version, but let’s go over one of the biggest changes that happened with the release of RC5, the @NgModule decorator. We can see it being used in the app.module.ts file.

// app.module.ts

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { HttpModule } from '@angular/http';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    FormsModule,
    HttpModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

So what exactly is happening here? The @NgModule decorator specifies all declarations (components, directives and pipes), library imports (such as FormsModule and HttpModule) and providers (a single-instance service for example) that we’ll be using in our application.

You can probably already see how much more organized it is to not need to specify all our module-level components, directives, pipes and so forth in each of our components.

Let’s get ready to rumble

Let’s set up Sass as our CSS preprocessor. The CLI makes it simple for a project that’s already been started.

ng set defaults.styleExt scss

Note: If you’re seeing a weird error here, you can just set the default style extension to scss in angular-cli.json instead and restart the server. Take a look at this issue.

Now that we have everything set up, we can create our first few components. To start things off, we’ll create a HeaderComponent.

ng generate component Header

You’ll notice that a header folder is immediately created and scaffolded with the following files created.

header.component.scss
header.component.html
header.component.ts
header.component.spec.ts

I’m only joking, unit testing is always important for apps that go to production. We won’t be doing them for this tutorial however so feel free to delete/comment out the spec files.

Take a look at app.module.ts once again and you’ll notice that our component is now declared there as well.

// app.module.ts

// ...
import { AppComponent } from './app.component';
import { HeaderComponent } from './header/header.component';

@NgModule({
  declarations: [
    AppComponent,
    HeaderComponent
  ],
//...

If you take a look at header.component.ts, you can see that its component selector is app-header. Let’s add this in our root component, app.component.ts.

<!-- app.component.html -->

<app-header></app-header>

Running the application will show you that the header component loads successfully.

Sweet, now let’s add some markup and styling.

<!-- app.component.html -->

<div id="wrapper">
  <app-header></app-header>
</div>

The styling in app.component.scss can be found here. Now let’s work on the header.

<!-- header.component.html -->

<header id="header">
  <a class="home-link" href="/">
    <img class="logo" src="https://i.imgur.com/J303pQ4.png">
  </a>
  <div class="header-text">
    <div class="left">
      <h1 class="name">
        <a href="/">Angular 2 HN</a>
      </h1>
      <span class="header-nav">
        <a href="">new</a>
        <span class="divider">
          |
        </span>
        <a href="">show</a>
        <span class="divider">
          |
        </span>
        <a href="">ask</a>
        <span class="divider">
          |
        </span>
        <a href="">jobs</a>
      </span>
    </div>
    <div class="info">
      Built with <a href="https://cli.angular.io/" target="_blank">Angular CLI</a>
    </div>
  </div>
</header>

And similarly, you can find the styling for this component here. Running the application gives us the following result.

View Encapsulation

Since we want this application to be as responsive as possible, it’s important to check how it looks with different screen sizes regularly. Let’s adjust our viewport to see how it would look on a mobile device.

As you can see, there seems to be an offset from the edge of the page. This is because the body element has a bult-in offset (through margin) that shows in almost all modern browsers.

But if you take a look at app.component.scss, we explicity set margin: 0 for screen sizes less then 768px.

$mobile-only: "only screen and (max-width : 768px)";

body {
  margin-bottom: 0;

  @media #{$mobile-only} {
    margin: 0;
  }
}

So why isn’t this rendering the way it should? This is because of the way Angular encapsulates CSS styles onto a component. I won’t be going into too much detail here, but there are three different ways Angular does this.

None: Angular doesn’t do anything. No encapsulation and no Shadow DOM, this is just like adding styles regularly. Adding a style will apply to the entire document.
Emulated: Angular emulates Shadow DOM behaviour. This is the default.
Native: Angular uses the browser’s native Shadow DOM completely (make sure you’re using a browser that supports this.

In our root component, we’re trying to add styles to the body element which really doesn’t make sense if you think about it. Our root component is within body, not the other way around, hence why it’s styles will not be affected. We can work around this by telling Angular to not do any view encapsulation in this component whatsoever.

// app.component.ts

import { Component, ViewEncapsulation } from '@angular/core';

@Component({
  selector: 'app-root',
  encapsulation: ViewEncapsulation.None,
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})

export class AppComponent {
}

Take a look at our application once more and you’ll notice that the styles have now been applied to body. This is because all of the styles in this component now affect the entire document.

But wait a minute, was all of this really necessary? I see a styles.css file in our src folder. Isn’t this for global styles? Can’t we just add a class here to style body?

Yes you can, but hey at least we learned something here.

Multiple Components

Let’s create two more components, Stories and Footer. Stories represent posts in Hacker News, and we’ll start out with a skeleton just to get an ordered list in place.

ng g component Stories

// stories.component.ts

import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-stories',
  templateUrl: './stories.component.html',
  styleUrls: ['./stories.component.scss']
})

export class StoriesComponent implements OnInit {
  items: number[];

  constructor() {
    this.items = Array(30);
  }

  ngOnInit() {
  }
}

<!-- stories.component.html -->

<div class="main-content">
  <ol>
    <li *ngFor="let item of items; let i = index" class="post">
      Story #{{i}}
    </li>
  </ol>
  <div class="nav">
    <a href="" class="prev">
      ‹ Prev
    </a>
    <a href="" class="more">
      More ›
    </a>
  </div>
</div>

Click here to take a look at the styles for Stories. Our footer is straightfoward (and it’s styling can be found here).

ng g component Footer

<!-- footer.component.html -->

<div id="footer">
    <p>Show this project some ❤ on
      <a href="https://github.com/housseindjirdeh/angular2-hn" target="_blank">
        GitHub
      </a>
    </p>
</div>

We’ll also need to update our root component to show these components.

<!-- app.component.html -->

<div id="wrapper">
  <app-header></app-header>
  <app-stories></app-stories>
  <app-footer></app-footer>
</div>

Let’s see what our page is looking like.

Since each post, or item, will have its own attributes, it makes sense to create a component for this as well.

ng g component Item

Once we start getting real data, we’ll need to pass down the item identifier from the story component to it’s child item component. In the meantime, let’s just pass down the list index as itemID.

<!-- stories.component.html -->

<div class="main-content">
  <ol>
    <li *ngFor="let item of items; let i = index" class="post">
      <item class="item-block" itemID="{{ i + 1 }}"></item>
    </li>
  </ol>
  <div class="nav">
    <a href="" class="prev">
      ‹ Prev
    </a>
    <a href="" class="more">
      More ›
    </a>
  </div>
</div>

// item.component.ts

import { Component, Input, OnInit } from '@angular/core';

@Component({
  selector: 'item',
  templateUrl: './item.component.html',
  styleUrls: ['./item.component.scss']
})
export class ItemComponent implements OnInit {
  @Input() itemID: number;

  constructor() { }

  ngOnInit() {
  }

}

<!-- item.component.html -->

<p>Story #{{itemID}}<p>

Refreshing the application will give you the same result, showing that the index parameter is successfully being passed down using the @Input decoration.

We have a basic skeleton of the home page done and that’s a good start. Here’s the link for the source code for this step.

RxJS and Observables

Before we start fetching real data, let’s briefly go over the concept of RxJS and observables.

Angular’s HTTP client allows you to communicate with a server, and you need it to fetch data from anywhere. To fetch data from a server, the first thing you would most likely do is pass the resource URL through an http.get call. But what gets returned exactly?

In Angular 2, we use the RxJS library to return an Observable of data, or an asynchronous stream of data. You may already be familiar with the concept of Promises and how you can use them to retrieve data asynchronously. Observables obtain data just like promises do, but they allow us to subscribe to the stream of data and respond to specific data changes that it emits.

Source: The introduction to Reactive Programming you’ve been missing

The diagram above depicts the events that occur when a user clicks on a button. Notice how this stream emits values (which represent the click events), an error as well as a completed event.

The entire concept of using Observables in your application is known as Reactive Programming.

Observable Data Service

Okay, now it’s time to start retrieving some real data. To do this, we’re going to be creating an Observable Data Service and injecting it into our components.

ng g service hackernews-api

This creates and sets up a service file for us. Now before we dive in, let’s try to understand how the official Hacker News API works. If you take a look at the documentation, you’ll notice that everything (polls, comments, stories, jobs) is just an item distinguishable though an id parameter. This means any item’s information can be obtained from their specific URL.

// https://hacker-news.firebaseio.com/v0/item/2.json?print=pretty

{
  "by" : "phyllis",
  "descendants" : 0,
  "id" : 2,
  "kids" : [ 454411 ],
  "score" : 16,
  "time" : 1160418628,
  "title" : "A Student's Guide to Startups",
  "type" : "story",
  "url" : "https://www.paulgraham.com/mit.html"
}

Now if we want to obtain information like front page ranking, we’ll need to use another endpoint specific to the type of stories. For example, top stories can be retrieved like this.

// https://hacker-news.firebaseio.com/v0/topstories.json?print=pretty

[ 12426766, 12426315, 12424656, 12425725, 12426064, 12427341, 12425692, 12425776, 12425324, 12425750, 12425135, 12427073, 12425632, 12423733, 12425720, 12427135, 12425683, 12423794, 12424987, 12423809, 12424738, 12425119, 12426759, 12425711, 12422891, 12424731, 12423742, 12424131, 12424184, 12422833, 12424421, 12426729, 12423373, 12421687, 12427437 ...]

So to show the top stories on the front page, we’ll need to first subscribe to this endpoint and then subsequently subscribe to each item. Let’s dive in.

Since we would want a single instance of the service throughout the entire app, let’s include it in the provider metadata of NgModule.

// app.module.ts

//...
import { HackerNewsAPIService } from './hackernews-api.service';

@NgModule({
  declarations: [
    ...
   ],
  imports: [
    ...
  ],
  providers: [HackerNewsAPIService],
  bootstrap: [AppComponent]
})
export class AppModule { }

Now let’s add the request method to our service.

// hackernews-api.service.ts

import { Injectable } from '@angular/core';
import { Http } from '@angular/http';
import { Observable } from 'rxjs/Observable';
import 'rxjs/add/operator/map';

@Injectable()
export class HackerNewsAPIService {
  baseUrl: string;

  constructor(private http: Http) {
    this.baseUrl = 'https://hacker-news.firebaseio.com/v0';
  }

  fetchStories(): Observable<any> {
    return this.http.get(`${this.baseUrl}/topstories.json`)
                    .map(response => response.json());
  }
}

As we mentioned previously, the http.get call returns an Observable of data. If you look at fetchStories, we take in the Observable and then map it to a JSON format. Let’s see how we handle this Observable in our component.

// stories.component.ts

import { Component, OnInit } from '@angular/core';
import { Observable } from 'rxjs/Observable';

import { HackerNewsAPIService } from '../hackernews-api.service';

@Component({
  selector: 'app-stories',
  templateUrl: './stories.component.html',
  styleUrls: ['./stories.component.scss']
})

export class StoriesComponent implements OnInit {
  items;

  constructor(private _hackerNewsAPIService: HackerNewsAPIService) {}

  ngOnInit() {
    this._hackerNewsAPIService.fetchStories()
                    .subscribe(
                      items => this.items = items,
                      error => console.log('Error fetching stories'));
  }
}

In the ngOnInit hook, which fires when the component is initialized, we subscribe to the data stream and set the items attribute to what gets returned. In our view, the only thing we’re going to add is a SlicePipe to show 30 list items instead of all 500 which gets returned.

<!-- stories.component.html -->

<div class="main-content">
  <ol>
    <li *ngFor="let item of items | slice:0:30" class="post">
      <item class="item-block" itemID="{{ item }}"></item>
    </li>
  </ol>
  <!-- ... -->
</div>

Now if you run the application, you’ll see a list of item ids populated.

Since we have the item id’s being passed down successfully to each of the item components, let’s set up another Observable subscription for each item to show their details. To do this, let’s start by adding a new method to our service.

// hackernews-api.service.ts

//...

fetchItem(id: number): Observable<any> {
  return this.http.get(`${this.baseUrl}/item/${id}.json`)
                  .map(response => response.json());
}

And now we need to modify our item component a bit.

// item.component.ts

import { Component, Input, OnInit } from '@angular/core';

import { HackerNewsAPIService } from '../hackernews-api.service';

@Component({
  selector: 'item',
  templateUrl: './item.component.html',
  styleUrls: ['./item.component.scss']
})
export class ItemComponent implements OnInit {
  @Input() itemID: number;
  item;

  constructor(private _hackerNewsAPIService: HackerNewsAPIService) {}

  ngOnInit() {
    this._hackerNewsAPIService.fetchItem(this.itemID).subscribe(data => {
      this.item = data;
    }, error => console.log('Could not load item' + this.itemID));
  }
}

<!-- item.component.html -->

<div *ngIf="!item" class="loading-section">
  <!-- You can add a loading indicator here if you want to :) </i> -->
</div>
<div *ngIf="item">
  <div class="item-laptop">
    <p>
      <a class="title" href="{{item.url}}">
        {{item.title}}
      </a>
      <span class="domain">{{item.url | domain}}</span>
    </p>
    <div class="subtext-laptop">
      {{item.score}} points by
      <a href="">{{item.by}}</a>
      {{ (item.time | amFromUnix) | amTimeAgo }}
      <a href="">
        <span *ngIf="item.descendants !== 0">
          {{item.descendants}}
          <span *ngIf="item.descendants === 1">comment</span>
          <span *ngIf="item.descendants > 1">comments</span>
        </span>
        <span *ngIf="item.descendants === 0">discuss</span>
      </a>
    </div>
  </div>
  <div class="item-mobile">
    <!-- Markup that shows only on mobile (to give the app a
    responsive mobile feel). Same attributes as above
    nothing really new here (but refer to the source
    file if you're interested) -->
  </div>
</div>

Nice and straightforward. For each item, we’re subscribing to their respective stream. In the markup, we can see that when the response hasn’t been received yet, we have a loading section where we can show a loading indicator of some sort. Once the item loads from the Observable, it’s details will show. Click here to see all the files for this component including styling.

Note: You may be wondering where the amFromUnix and amTimeAgo pipes came from. The time parameter for each item is in Unix format. To convert this into something we can understand, I use moment.js pipes by importing the angular2-moment library.

Note 2: For each item with a link, the entire URL is passed through it’s url attribute. To only show the link domain, I created a pipe called domain. Take a look here for the code.

Now if you run the application, you’ll see the first page of Hacker News! Click here for the full source code until this step.

Things are kinda slow though

Let’s take a look at the requests transferred when we load the front page of our application.

Woah, 31 requests and 20.8KB transferred in 546ms. This takes almost five times as long loading the front page of Hacker News and more then twice as much data to just load the posts. This is pretty darn slow, and maybe it’s kind of tolerable when you’re loading the list of posts on the front page but this is a serious problem if we try loading a large number of comments for a single post.

I built the entire application with each component using this method, including each post and their comments. You can take a look at what happens when I try to load a post with almost 2000 comments here. But to save you time from watching that entire gif, it takes 741 requests, 1.5MB and 90s to load roughly 700 of the comments (I wasn’t patient enough to wait for every comment to load).

Just for reference’s sake, I still have this version of the app up on my GitHub pages. At your own caution, you can take a look at how long it takes to load this many comments here.

Let’s switch things up

Okay, now we can see why having multiple network connections to fetch a parent item and it’s content isn’t the nicest experience. After a little bit of searching, I found this awesome unofficial API which returns an item and it’s details through a single request.

For example, the response for the list of top stories looks like this.

// https://node-hnapi.herokuapp.com/news?page=1

[
  {
    "id": 12469856,
    "title": "Owl Lisp – A purely functional Scheme that compiles to C",
    "points": 57,
    "user": "rcarmo",
    "time": 1473524669,
    "time_ago": "2 hours ago",
    "comments_count": 9,
    "type": "link",
    "url": "https://github.com/aoh/owl-lisp",
    "domain": "github.com"
  },
  {
    "id": 12469823,
    "title": "How to Write Articles and Essays Quickly and Expertly",
    "points": 52,
    "user": "bemmu",
    "time": 1473524142,
    "time_ago": "2 hours ago",
    "comments_count": 6,
    "type": "link",
    "url": "https://www.downes.ca/post/38526",
    "domain": "downes.ca"
  },
  ...
]

Notice that there is a domain as well as a time_ago attribute which is pretty cool. This means we can ditch the domain.pipe.ts file I created earlier as well as uninstall the angular2-moment library. Let’s take a look at what we need to change in our data service.

// hackernews-api.service.ts

export class HackerNewsAPIService {
  baseUrl: string;

  constructor(private http: Http) {
    this.baseUrl = 'https://node-hnapi.herokuapp.com';
  }

  fetchStories(storyType: string, page: number): Observable<any> {
    return this.http.get(`${this.baseUrl}/${storyType}?page=${page}`)
                    .map(response => response.json());
  }
}

Since the API doesn’t load all 500 top stories, we need to add page number as an argument. Notice how we’re also passing storyType as well. This will allow us to show different types of stories depending on where the user navigates to.

Let’s take a look at how we can change the stories component. We can start with just passing in 'news' and page number 1 into our service call to get our top stories.

// stories.component.ts

export class StoriesComponent implements OnInit {
  items;

  constructor(private _hackerNewsAPIService: HackerNewsAPIService) {}

  ngOnInit() {
    this._hackerNewsAPIService.fetchStories('news', 1)
                              .subscribe(
                                items => this.items = items,
                                error => console.log('Error fetching stories'));
  }
}

The correpsonding markup is as follows.

<!-- stories.component.html -->

<div class="loading-section" *ngIf="!items">
  <!-- You can add a loading indicator here if you want to :) -->
</div>
<div *ngIf="items">
  <ol>
    <li *ngFor="let item of items" class="post">
      <item class="item-block" [item]="item"></item>
    </li>
  </ol>
  <div class="nav">
    <a class="prev">
      ‹ Prev
    </a>
    <a class="more">
      More ›
    </a>
  </div>
</div>

Since all our item components are not loading individually async anymore, we set up the loading section (where we can have a loading indicator) here. Moreover, we just pass in the item object of each post to the child item component.

This means we should be able to clean things up in ItemComponent. In item.component.ts, we don’t need to inject HackerNewsService anymore and our component is now simply a conduit to take in the item object from it’s parent.

// item.component.ts

export class ItemComponent implements OnInit {
  @Input() item;

  constructor() {}

  ngOnInit() {

  }
}

The markup (item.component.html) is very similar, but we now don’t need to conditionally check if the item object is present anymore (we do that in the parent component). Moreover, each parameter now refers to the properties of our new API.

<!-- item.component.html -->

<div class="item-laptop">
  <p>
    <a class="title" href="">
      {{item.title}}
    </a>
    <span *ngIf="item.domain" class="domain">({{item.domain}})</span>
  </p>
  <div class="subtext-laptop">
    <span>
      {{item.points}} points by
      <a href="">{{item.user}}</a>
    </span>
    <span>
      {{item.time_ago}}
      <span> |
        <a href="">
          <span *ngIf="item.comments_count !== 0">
            {{item.comments_count}}
            <span *ngIf="item.comments_count === 1">comment</span>
            <span *ngIf="item.comments_count > 1">comments</span>
          </span>
          <span *ngIf="item.comments_count === 0">discuss</span>
        </a>
      </span>
    </span>
  </div>
</div>
<div class="item-mobile">
  <!-- Markup that shows only on mobile (to give the app a
    responsive mobile feel). Same attributes as above
    nothing really new here (but refer to the source
    file if you're interested) -->
</div>

Now let’s see what happens when we run this bad boy.

And now everything loads much faster. The source code for this step can be found here.

Routing

We’ve come quite a long way, but before we continue let’s map out the entire component structure of the application. Please excuse my funky Powerpoint skills.

Let’s start with what we’ve built so far.

Let’s also map out the components that show when we navigate to the comments page.

To allow the user to navigate between these pages, we’re going to have to include some basic routing in our application. Before we begin, let’s create our next component.

ng g component ItemComments

Now let’s create an app.routes.ts file in our app folder.

// app.routes.ts

import { Routes, RouterModule } from '@angular/router';

import { StoriesComponent } from './stories/stories.component';
import { ItemCommentsComponent } from './item-comments/item-comments.component';

const routes: Routes = [
  {path: '', redirectTo: 'news/1', pathMatch : 'full'},
  {path: 'news/:page', component: StoriesComponent, data: {storiesType: 'news'}},
  {path: 'newest/:page', component: StoriesComponent, data: {storiesType: 'newest'}},
  {path: 'show/:page', component: StoriesComponent, data: {storiesType: 'show'}},
  {path: 'ask/:page', component: StoriesComponent, data: {storiesType: 'ask'}},
  {path: 'jobs/:page', component: StoriesComponent, data: {storiesType: 'jobs'}},
  {path: 'item/:id', component: ItemCommentsComponent}
];

export const routing = RouterModule.forRoot(routes);

An overview of what we’re doing here:

We just created an array of routes, each with a relative path that maps to a specific component
Our header navigation links will route to a number of different paths; news, newest, show, ask and jobs. All these paths will map to our StoriesComponent
We’ve set up our root path to redirect to news which should return the list of top stories
When we map to StoriesComponent, we pass down storiesType as a parameter through the data property. This lets us have a story type associated for each route (we’ll need this when we use our data service to fetch the list of stories)
:page is used as a token so that StoriesComponent can fetch the list of stories for a specific page
:id is similarly used so that ItemCommentsComponent can obtain all the comments for a specific item

There’s a lot more you can do with routing, but this basic setup should be everything we need. Now let’s open app.module.ts to register our routing.

// app.module.ts

// ...
import { routing } from './app.routes';

@NgModule({
  declarations: [
    //...
  ],
  imports: [
    //...
    routing
  ],
  providers: [HackerNewsAPIService],
  bootstrap: [AppComponent]
})
export class AppModule { }

To tell Angular where to load the component to route to, we need to use RouterOutlet.

<!-- app.component.html -->

<div id="wrapper">
  <app-header></app-header>
  <router-outlet></router-outlet>
  <app-footer></app-footer>
</div>

Let’s bind our navigation links in HeaderComponent to their respective routes.

<!-- header.component.html -->

<header>
  <div id="header">
    <a class="home-link" routerLink="/news/1">
      <img class="logo" src="https://i.imgur.com/J303pQ4.png">
    </a>
    <div class="header-text">
      <div class="left">
        <h1 class="name">
          <a routerLink="/news/1" class="app-title">Angular 2 HN</a>
        </h1>
        <span class="header-nav">
          <a routerLink="/newest/1">new</a>
          <span class="divider">
            |
          </span>
          <a routerLink="/show/1">show</a>
          <span class="divider">
            |
          </span>
          <a routerLink="/ask/1">ask</a>
          <span class="divider">
            |
          </span>
          <a routerLink="/jobs/1">jobs</a>
        </span>
      </div>
      <div class="info">
        Built with <a href="https://cli.angular.io/" target="_blank">Angular CLI</a>
      </div>
    </div>
  </div>
</header>

The RouterLink directive is responsible for binding a specific element to a route. Let’s update the StoriesComponent now.

// stories.component.ts

import { Component, OnInit } from '@angular/core';
import { Observable } from 'rxjs/Observable';
import { ActivatedRoute } from '@angular/router';

import { HackerNewsAPIService } from '../hackernews-api.service';

@Component({
  selector: 'app-stories',
  templateUrl: './stories.component.html',
  styleUrls: ['./stories.component.scss']
})

export class StoriesComponent implements OnInit {
  typeSub: any;
  pageSub: any;
  items;
  storiesType;
  pageNum: number;
  listStart: number;

  constructor(
    private _hackerNewsAPIService: HackerNewsAPIService,
    private route: ActivatedRoute
  ) {}

  ngOnInit() {
    this.typeSub = this.route
      .data
      .subscribe(data => this.storiesType = (data as any).storiesType);

    this.pageSub = this.route.params.subscribe(params => {
      this.pageNum = +params['page'] ? +params['page'] : 1;
      this._hackerNewsAPIService.fetchStories(this.storiesType, this.pageNum)
                              .subscribe(
                                items => this.items = items,
                                error => console.log('Error fetching' + this.storiesType + 'stories'),
                                () => this.listStart = ((this.pageNum - 1) * 30) + 1);
    });
  }
}

Let’s parse out what we’ve added. First of all, we imported ActivatedRoute which is a service that allows us to access information present in the route.

import { ActivatedRoute } from '@angular/router';

@Component({
  //...
})

export class StoriesComponent implements OnInit {
//..

constructor(
  private route: ActivatedRoute
) {}
//...
}

We then subscribe to the route data property and store storiesType into a component variable in the ngOnInit hook. Notice how we assign any type to the response object. This is just a quick and simple way to opt-out of type checking. Otherwise you may see an error that states property storiesType does not exist.

ngOnInit() {
  this.typeSub = this.route
    .data
    .subscribe(data => this.storiesType = (data as any).storiesType);

// ...
}

And finally, we subscribe to the route parameters and obtain the page number. We then fetch the list of stories using our data service.

ngOnInit() {
// ...

this.pageSub = this.route.params.subscribe(params => {
    this.pageNum = +params['page'] ? +params['page'] : 1;
    this._hackerNewsAPIService.fetchStories(this.storiesType, this.pageNum)
                            .subscribe(
                              items => this.items = items,
                              error => console.log('Error fetching' + this.storiesType + 'stories'),
                              () => {
                                this.listStart = ((this.pageNum - 1) * 30) + 1;
                                window.scrollTo(0, 0);
                              });
  });
}

To signal completion, we use onCompleted() to update a listStart variable which is used as the starting value of our ordered list (which you can see in the markup below). We also scroll to the top of the window so the user is not stuck at the bottom of the page when he/she tries to switch pages.

<!-- stories.component.html -->

<div class="main-content">
  <div class="loading-section" *ngIf="!items">
    <!-- You can add a loading indicator here if you want to :) -->
  </div>
  <div *ngIf="items">
    <ol start="{{ listStart }}">
      <li *ngFor="let item of items" class="post">
        <item class="item-block" [item]="item"></item>
      </li>
    </ol>
    <div class="nav">
      <a *ngIf="listStart !== 1" [routerLink]="['/' + storiesType, pageNum - 1]" class="prev">
        ‹ Prev
      </a>
      <a *ngIf="items.length === 30" [routerLink]="['/' + storiesType, pageNum + 1]" class="more">
        More ›
      </a>
    </div>
  </div>
</div>

We now have the front page complete with navigation and pagination. Run the application to see the good stuff.

Item Comments

We’re almost done! Before we start adding our other comment page components, let’s update the links in ItemComponent to include routing.

<!-- item.component.html -->

<div class="item-laptop">
  <p>
    <a class="title" href="{{item.url}}">
      {{item.title}}
    </a>
    <span *ngIf="item.domain" class="domain">({{item.domain}})</span>
  </p>
  <div class="subtext-laptop">
    <span>
      {{item.points}} points by
      <a href="">{{item.user}}</a>
    </span>
    <span>
      {{item.time_ago}}
      <span> |
         <a [routerLink]="['/item', item.id]">
          <span *ngIf="item.comments_count !== 0">
            {{item.comments_count}}
            <span *ngIf="item.comments_count === 1">comment</span>
            <span *ngIf="item.comments_count > 1">comments</span>
          </span>
          <span *ngIf="item.comments_count === 0">discuss</span>
        </a>
      </span>
    </span>
  </div>
</div>
<div class="item-mobile">
  <!-- Markup that shows only on mobile (to give the app a
    responsive mobile feel). Same attributes as above,  
    nothing really new here (but refer to the source
    file if you're interested) -->
</div>

Run the application and click on an item’s comments.

Beauty. We can see that it’s routing to ItemCommentsComponent. Now let’s create our additional components.

ng g component CommentTree

ng g component Comment

We should add a new GET request to our data service to fetch comments, so let’s do that before we start filling our components in.

// hackernews.api.service.ts

//...

fetchComments(id: number): Observable<any> {
  return this.http.get(`${this.baseUrl}/item/${id}`)
                  .map(response => response.json());
}

And now we can fill out our components.

// item-comments.component.ts

import { Component, OnInit } from '@angular/core';
import { ActivatedRoute } from '@angular/router';

import { HackerNewsAPIService } from '../hackernews-api.service';

@Component({
  selector: 'app-item-comments',
  templateUrl: './item-comments.component.html',
  styleUrls: ['./item-comments.component.scss']
})
export class ItemCommentsComponent implements OnInit {
  sub: any;
  item;

  constructor(
    private _hackerNewsAPIService: HackerNewsAPIService,
    private route: ActivatedRoute
  ) {}

  ngOnInit() {    
    this.sub = this.route.params.subscribe(params => {
      let itemID = +params['id'];
      this._hackerNewsAPIService.fetchComments(itemID).subscribe(data => {
        this.item = data;
      }, error => console.log('Could not load item' + itemID));
    });
  }
}

Similar to what we did in StoriesComponent, we subscribe to our route parameters, obtain the item id and use that to fetch our comments.

<!-- item-comments.component.html -->

<div class="main-content">
  <div class="loading-section" *ngIf="!item">
    <!-- You can add a loading indicator here if you want to :) -->
  </div>
  <div *ngIf="item" class="item">
    <div class="mobile item-header">
     <!-- Markup that shows only on mobile (to give the app a
    responsive mobile feel). Same attributes as below,
    nothing really new here (but refer to the source
    file if you're interested) -->
    </div>
    <div class="laptop" [class.item-header]="item.comments_count > 0 || item.type === 'job'" [class.head-margin]="item.text">
      <p>
        <a class="title" href="{{item.url}}">
        {{item.title}}
        </a>
        <span *ngIf="item.domain" class="domain">({{item.domain}})</span>
      </p>
      <div class="subtext">
        <span>
        {{item.points}} points by
          <a href="">{{item.user}}</a>
        </span>
        <span>
          {{item.time_ago}}
          <span> |
            <a [routerLink]="['/item', item.id]">
              <span *ngIf="item.comments_count !== 0">
                {{item.comments_count}}
                <span *ngIf="item.comments_count === 1">comment</span>
                <span *ngIf="item.comments_count > 1">comments</span>
              </span>
              <span *ngIf="item.comments_count === 0">discuss</span>
            </a>
          </span>
        </span>
      </div>
    </div>
    <p class="subject" [innerHTML]="item.content"></p>
    <app-comment-tree [commentTree]="item.comments"></app-comment-tree>
  </div>
</div>

At the top of the component, we’re going to display the item details, followed by it’s description (item.content). We then input the entire comments object (item.comments) to app-comment-tree, the selector for CommentTreeComponent. The styling for this component can be found here.

Next, set up the CommentTreeComponent.

// comment-tree.component.ts

import { Component, Input, OnInit } from '@angular/core';

@Component({
  selector: 'app-comment-tree',
  templateUrl: './comment-tree.component.html',
  styleUrls: ['./comment-tree.component.scss']
})
export class CommentTreeComponent implements OnInit {
  @Input() commentTree;

  constructor() {}

  ngOnInit() {

  }
}

<!-- comment-tree.component.html -->

<ul class="comment-list">
   <li *ngFor="let comment of commentTree" >
      <app-comment [comment]="comment"></app-comment>
   </li>
</ul>

Nice and simple, we list all the comments using the ngFor directive. Click here to see it’s SCSS file.

Let’s fill out CommentComponent, the component responsible for each specific comment.

// comment.component.ts

import { Component, Input, OnInit } from '@angular/core';

@Component({
  selector: 'app-comment',
  templateUrl: './comment.component.html',
  styleUrls: ['./comment.component.scss']
})
export class CommentComponent implements OnInit {
  @Input() comment;
  collapse: boolean;

  constructor() {}

  ngOnInit() {
    this.collapse = false;
  }
}

<!-- comment.component.html -->

<div *ngIf="!comment.deleted">
  <div class="meta" [class.meta-collapse]="collapse">
    <span class="collapse" (click)="collapse = !collapse">[{{collapse ? '+' : '-'}}]</span>
    <a [routerLink]="['/user', comment.user]" routerLinkActive="active">{{comment.user}}</a>
    <span class="time">{{comment.time_ago}}</span>
  </div>
  <div class="comment-tree">
    <div [hidden]="collapse">
      <p class="comment-text" [innerHTML]="comment.content"></p>
      <ul class="subtree">
        <li *ngFor="let subComment of comment.comments">
          <app-comment [comment]="subComment"></app-comment>
        </li>
      </ul>
    </div>
  </div>
</div>
<div *ngIf="comment.deleted">
  <div class="deleted-meta">
    <span class="collapse">[deleted]</span> | Comment Deleted
  </div>
</div>

Notice how we’re recursively referencing app-comment inside of it’s own component. This is because each comment object in the array has it’s own array of comments, and we’re using recursion to show all of them.

Click here to see the styling for this component. If you now run the application, you can see all the comments for each item!

The entire source code for this step can be found here.

User Profiles

All we have left is user profiles. Since the concept is pretty much the same, I won’t go through this in detail. All you need to do is:

Set up another request in the data service to point to the user endpoint
Create a user component
Add another field to your routes file
Update the user links in the other components to route to the user

And that’s it! Take a look here if you want to see the whole user component setup.

Wrapping things up

We’re done! To kick off a production build, you can run ng build --prod or ng serve --prod which will make use of uglifying and tree-shaking.

I hope you found this tutorial useful. If you did, please tweet it forward and/or star the repo! I would also love to hear any type of feedback whatsoever.

If you happen to be interested enough to work on this app further, take a look at the issue list and feel free to put up a feature request or a PR! There have been some structural and feature changes since I’ve written this post and this version of the app lives in a separate branch from master, so you’ll need to go there to see the latest version .

If you’re interested, please take a look at my post on how I made this a Progressive Web App that works offline and can be installed to your mobile homescreen!

Building Angular 2 applications with Immutable.js and Redux

Mon, 04 Jul 2016 13:30:00 +0000

If you have done any JavaScript development in the past year, then you may have already heard of Redux. Popularized with the use of React, some developers claim it’s the most exciting thing happening in JavaScript at the moment, revolutionizing the way we build our applications and even helping us prevent global warming for good.

Okay, I got a little carried away there. But seriously, Redux does sort of change the way you can build your applications. This post will explain how you can integrate it with Angular 2 alongside another library, Immutable.js.

The breakdown

In this post, we’ll go over the basic concepts of the Flux architecture and Redux. We’ll then go over a simple contact list application step by step, building the basic setup first, adding immutability then finally creating a Redux state container.

View App Source Code

As we go along, I’ll do my best to explain why we’re doing each and every step. The final application will not be complicated but will hopefully be enough for you to grasp the main concepts.

Redux and Flux Architecture

Flux is simply an architectural pattern to build user interfaces. It’s not a framework or library, it’s a design pattern for building client side applications.

Source: Flux Documentation - Structure and Data Flow

Redux is an implementation of Flux created by Dan Abramov. Although Flux is not a library on its own, Facebook has created a Dispatcher library in which a Flux-centered application can leverage. Redux follows the same architecture, but aims to make certain abstractions simpler.

Redux preserves all the benefits of Flux (recording and replaying of actions, unidirectional data flow, dependent mutations) and adds new benefits (easy undo-redo, hot reloading) without introducing Dispatcher and store registration.

Dan Abramov

Let’s look at its basic principles.

1) Everything that changes in your application is contained in a single JavaScript object, known as the store.
2) The store acts as the container for the application state.
3) The state is read-only and it cannot be modified (i.e. it is immutable).
4) To make changes to the state (this can be a user event or an API interaction), you need to send a JavaScript object describing the change. In other words, you need to dispatch an action.
6) Data is transferred from the store to the view and never the other way around. This means that the view cannot alter the state in any way.

As we mentioned, state mutations cannot alter the current state. In Redux, this means that a new JSON object must get returned everytime a mutation occurs. For this to happen, changes to the state need to be triggered through the use of pure functions. A pure function is a function that always returns the same value given the same input. In other words, it cannot modify anything outside of its own scope. This means it can’t alter external variables or make calls to a database.

function pureFunction(object){
  return object.a * 100;
}

var x = { a: 1 };
pureFunction(x);
console.log(x);
// x = { a: 1 }

function impureFunction(object){
  object.a = object.a * 100;
  return object.a;
}

var x = { a: 1 };
impureFunction(x);
console.log(x);
// x = { a: 100 }

In Redux, these are known as reducers and are responsible for determining how the application state changes in response to the actions.

Don’t worry if all of this isn’t crystal clear yet. It’ll make more sense as you go through this post and see how reducers, actions and the store are used in a real example.

Contact List Example

Let’s start building the contact list example! If you haven’t already, you can set up your application using the Angular 2 QuickStart. I’ll remove the unnecessary class definitions and styling elements in the code embeds and just show you what’s needed. However, I’ll link to the complete source code for each step.

To kick things off, let’s build a simple version with purely Angular elements. We’ll start with a contact store to handle the logic of our application.

// Contact Store

export class Contact {
  name: String;
  star: boolean;
}

export class ContactStore {
  contacts: Contact[];

  constructor() {
    this.contacts = [];
  }

  addContact(newContact: String) {
    this.contacts.push({
      name: newContact,
      star: false
    });
  }

  removeContact(contact: Contact) {
    const index = this.contacts.indexOf(contact);
    this.contacts.splice(index, 1);
  }

  starContact(contact: Contact) {
    const index = this.contacts.indexOf(contact);
    this.contacts[index].star = !this.contacts[index].star;
  }
}

This is very similar to how we would set up a service in Angular 1.x. This store now controls the state of the application where we have methods to add, remove and favourite contacts.

Now let’s set up our component.

// Contact List Component

import { Component } from '@angular/core';
import { ContactStore } from './contact-store';

@Component({
  selector: 'contact-list',
  templateUrl: 'app/contact-list.html',
  styleUrls: ['app/contact-list.css'],
})

export class ContactList {
  constructor(private store: ContactStore) { }

  addContact(contact) {
    this.store.addContact(contact);
  }

  removeContact(contact) {
    this.store.removeContact(contact);
  }

  starContact(contact) {
    this.store.starContact(contact);
  }
}

<!-- Contact List HTML -->

<input #newContact placeholder="Add Contact"
  (keyup.enter)="addContact(newContact.value); newContact.value='' ">
<ul>
  <li *ngFor="let contact of store.contacts">
    {{ contact.name }}
    <button (click)="starContact(contact)">
      <i class="fa fa-2x"
        [class.fa-star]="contact.star"
        [class.fa-star-o]="!contact.star"></i>
    </button>
    <button (click)="removeContact(contact)">
      <i class="fa fa-trash fa-2x"></i>
    </button>
  </li>
</ul>

In here, we have a constructor that defines a private store property and identifies it as a ContactStore injection site. The input property methods, addContact, removeContact and starContact, all link to their respective methods in the ContactStore.

So far we’ve built something simple which works, so that’s a good start. The source code for this can be found here.

Multiple Components

Since Angular 2 is component based, it makes more sense to have another component for each of the contacts. So let’s set the parent component to be the actual list.

// Contact List Component

import { Component } from '@angular/core';
import { ContactStore } from './contact-store';
import Contact from './contact';

@Component({
  selector: 'contact-list',
  templateUrl: 'app/contact-list.html',
  styleUrls: ['app/contact-list.css'],
  directives: [Contact]
})

export class ContactList {
  constructor(private store: ContactStore) { }

  addContact(contact) {
    this.store.addContact(contact);
  }
}

<!-- Contact List HTML -->
<input #newContact placeholder="Add Contact"
  (keyup.enter)="addContact(newContact.value); newContact.value='' ">
<ul>
  <li *ngFor="let contact of store.contacts">
    <contact [contact]="contact"></contact>
  </li>
</ul>

And the child component will just be that of the contact.

// Contact Component

import { Component, Input } from '@angular/core';
import { ContactStore, Contact as ContactModel} from './contact-store';

@Component({
  selector: 'contact',
  templateUrl: 'app/contact.html',
  styleUrls: ['app/contact.css'],
})

export default class Contact {
  @Input()
  contact: ContactModel;

  constructor(private store: ContactStore) { }

  removeContact(contact) {
    this.store.removeContact(contact);
  }

  starContact(contact) {
    this.store.starContact(contact);
  }
}

<!-- Contact HTML -->
<div class="contact-container">
  {{ contact.name }}
  <button (click)="starContact(contact)">
    <i class="fa fa-2x"
      [class.fa-star]="contact.star"
      [class.fa-star-o]="!contact.star"></i>
  </button>
  <button (click)="removeContact(contact)">
    <i class="fa fa-trash fa-2x"></i>
  </button>
</div>

As you can see, the store instance was injected to both the parent and child components. Things are looking a little cleaner now. The source code for this can be found here.

Change Detection Strategy

In Angular 2, each and every component has its own change detector responsible for bindings in their own template. For example, we have the {{ contact.name }} binding for which the Contact component is responsible for. In other words, the change detection behind the Contact component projects the data for contact.name as well as its change.

So what really happens when an event is triggered? In Angular 1.x, when a digest cycle is fired, every binding is triggered in the entire application. Similarly in Angular 2, every single component is also checked. Now wouldn’t it be cool to tell Angular to run change detection on a component only if one of its input properties changed instead of every time an event happens? We can by using Angular’s ChangeDetectionStrategy in our component level.

// Contact Component

import {..., ChangeDetectionStrategy} from '@angular/core';

@Component({
  selector: 'contact',
  templateUrl: 'app/contact.html',
  styleUrls: ['app/contact.css'],
  changeDetection: ChangeDetectionStrategy.OnPush
})

It’s as simple as that! Now the change detection for this component will only fire if changes occur to bindings within the component.

Now does this really matter in a simple application like this? Not really, since there aren’t that many bindings in the application in the first place. But for a huge application, this can help significantly reduce the number of bindings to consider when an event is triggered.

The case for Immutability

To take advantage of this change detection strategy, we need to ensure that the state is indeed immutable. However, the nature of JavaScript objects are by default, mutable. We can solve this by using Immutable.js, a library created by the Facebook team.

Immutable collections should be treated as values rather than objects. While objects represents some thing which could change over time, a value represents the state of that thing at a particular instance of time.

Immutable.js - The case for Immutability

Simply put, immutable objects are essentially objects that cannot change. If we wanted to modify them, we’ll create a new referenced object with that change and keep the original intact. Immutable.js provides a number of immutable data structures that we can include into our applications.

You can install immutable with npm install immutable. Once that’s complete, you may have to update your SystemJS configuration. If you’ve set up your application following the Angular 2 QuickStart, then this would be in the systemjs.config.js file. You’ll just need to add another mapped field so the system loader can look for the right file when immutable is referenced.

/**
 * System configuration for Angular 2 samples
 * Adjust as necessary for your application needs.
 */
(function(global) {
  // map tells the System loader where to look for things
  var map = {
    'app':                        'app', // 'dist',
    '@angular':                   'node_modules/@angular',
    'angular2-in-memory-web-api': 'node_modules/angular2-in-memory-web-api',
    'rxjs':                       'node_modules/rxjs',
    'immutable':                  'node_modules/immutable/dist/immutable.js'
  };
// ...

And that’s it! Now let’s update the ContactStore.

// Contact Store

import Immutable = require('immutable');

export class Contact {
  name: String;
  star: boolean;
}

export class ContactStore {
  contacts = Immutable.List<Contact>();

  addContact(newContact: String) {
    this.contacts = this.contacts.push({
      name: newContact,
      star: false
    });
  }

  removeContact(contact: Contact) {
    const index = this.contacts.indexOf(contact);
    this.contacts = this.contacts.delete(index);
  }

  starContact(contact: Contact) {
    const index = this.contacts.indexOf(contact);
    this.contacts = (<any>this.contacts).update(index, (contact) => {
      return {
        name: contact.name,
        star: !contact.star
      };
    });
  }
}

As you can see, we changed the instantiation of contacts and instead of an array, we’re using List instead. List is similar to the JavaScript array, but is immutable and completely persistent.

To persist changes to the list, we’re using the push, delete and update methods. Similar to an array, indexOf is also used to find the selected contact in the list. It’s important to remember that for all these methods, the current collection is not mutated but a new immutable collection is generated.

Here’s the link to the source code for this step.

Note: You may be wondering why <any> was used in the starContact method. This is just TypeScript type assertion to prevent compiler errors when returning an updated contact object. This is just a workaround due to an issue with type definitions when running methods against a list (discussed here).

Let’s make things spicy with Redux

You can install Redux with npm install --save redux. You’ll also need to update your system configuration once again.

var map = {
  '...':                        '...',
  'redux':                      'node_modules/redux/dist/redux.js'
};
// ...

Let’s add our actions file now.

// Actions

import { Contact as ContactModel} from './contact-store';

export interface IContactAction {
  type: string;
  id: number;
  name?: string;
}

export function addContact(name: string, id: number): IContactAction {
  return {
    type: 'ADD',
    id,
    name
  };
}

export function removeContact(id: number): IContactAction {
  return {
    type: 'REMOVE',
    id
  };
}

export function starContact(id: number): IContactAction {
  return {
    type: 'STAR',
    id
  };
}

As you can see, all the actions are just simple JavaScript objects. For example:

{
  type: 'ADD',
  id,
  name
}

With Redux, actions must have a type property which describes the type of the action being executed. It’s also recommended that they be defined as string constants. Other than this, you can set up the structure of an action any way you like. I’ve set it up to include only what’s needed for each action, id and name to add a contact and just id to remove or favourite.

You can see that each of the actions are enclosed in functions that create them.

export function addContact(name: string, id: number): IContactAction {
  return {
    type: 'ADD',
    id,
    name
  };
}

These are known as action creators, and each one is defined to the IContactAction interface that we created.

Now let’s see how we can set up a reducer.

// Reducer

import Immutable = require('immutable');
import { IContactAction } from './actions';
import { Contact as ContactModel} from './contact-store';

export function reducer(state: Immutable.List<ContactModel> = Immutable.List<ContactModel>(), action: IContactAction) {
  switch (action.type) {
    case 'ADD':
      return state.push({
        id: action.id,
        name: action.name,
        star: false
      });
    case 'REMOVE':
      return state.delete(findIndexById());
    case 'STAR':
      return (<any>state).update(findIndexById(), (contact) => {
        return {
          id: contact.id,
          name: contact.name,
          star: !contact.star
        };
      });
    default:
      return state;
  }

  function findIndexById() {
    return state.findIndex((contact) => contact.id === action.id);
  }
}

Remember what we said earlier about pure functions? You can see that our reducer does not mutate the state or perform any side effects. For each of the actions, it just returns the newly generated state.

Let’s make the necessary updates to our store.

// Contact Store

import Immutable = require('immutable');
import { createStore } from 'redux';
import { IContactAction } from './actions';
import { reducer } from './reducer';

export class Contact {
  id: number;
  name: String;
  star: boolean;
}

export class ContactStore {
  store = createStore(reducer, Immutable.List<Contact>());

  get contacts(): Immutable.List<Contact> {
    return this.store.getState();
  }

  dispatch(action: IContactAction) {
    this.store.dispatch(action);
  }
}

Looks nice and straightforward. The createStore method creates a Redux store that holds the complete state of the application. For its second argument, the preloaded state of the application, we’re injecting the immutable contacts list. The current state is accessed with getState and actions are dispatched with the dispatch method.

We also added an id field to the Contact class. Now let’s update our component contact methods.

// Contact List Component

// ...
import { addContact } from './actions';

@Component({
// ...
})

export class ContactList {
  contactID: number;

  constructor(private store: ContactStore) {
    this.contactID = 0;
  }

  addContact(contact) {
    this.store.dispatch(addContact(contact, this.contactID++));
  }
}

As you can see, an incrementing ID value is set to each contact that is added. We import the appropriate action from actions and run the action through dispatch. Now taking a look at our child component.

// Contact Component

// ...
import { removeContact, starContact } from './actions';

@Component({
// ...
})

export default class Contact {
// ...
  removeContact(contact) {
    this.store.dispatch(removeContact(contact.id));
  }

  starContact(contact) {
    this.store.dispatch(starContact(contact.id));
  }
}

And that’s it! That covers up the basics of using Redux in your application. The final source code is here.

Wrapping things up

As you may have noticed, implementing immutable collections along with a redux state container adds some complexity to your application. This isn’t the only way to build Angular applications, nor is it the best way. It’s one way and it can make things easier under certain circumstances

Why should I care about immutability?

By default, Angular’s change detection checks every component with any change in the application. Enforcing immutability allows you to use ChangeDetectionStrategy.OnPush on some of your components so that they get triggered only when they need to (i.e. when their input properties change). A nice and simple way to enforce this is by using a library like Immutable.js.

When should I use Redux?

A better question would be, when should I be implementing a Flux style architecture in my application? I can’t answer it any better than this.

Event and Style binding in Angular 2

Sun, 29 May 2016 11:13:00 +0000

Angular 2 introduces new template syntax and directives that allow us to manipulate data in our applications. In this post, I begin with a brief introduction on data and event binding then dive right in to using style and class binding as well as directives to dynamically apply CSS and CSS classes.

One-way data binding

In Angular, data binding describes the synchronization between model and view. To explain this simply, assume we have a simple expression in our template.

<h1>{{firstname}}</h1>

Whenever the expression {{firstname}} changes, we want the DOM to update. The processes that trigger this instant update of the DOM is known as data binding and one-way refers to the directional flow of data from model to view.

Two-way data binding

Two-way data binding explains how the view updates when the model changes and vice-versa. This happens immediately which means that the model and view are always in-sync. In other words, you can think of the view as an instant projection of the model.

Source: AngularJS Developer Guide - Data Binding

Lets look at a simple example of how this works.

<h1>{{firstname}}</h1>
Name: <input type="text" [(ngModel)]="firstname">

export class MyApp {
  firstname: string = 'Jimmy';
}

We can see that the HTML is similar to what you would see in Angular 1.x. However, the two way binding syntax, [(ngModel)], is slightly different.

Just as you would expect, changing the input value changes the interpolation {{firstname}} which is evidence that the value is flowing to the model and vice-versa.

Event Binding

Now let’s add a click event to make things a little more exciting.

<h1>{{firstname}}</h1>
Name: <input type="text" [(ngModel)]="firstname">
<button (click)="changeName()">Change Name</button>

export class MyApp {
  firstname: string = 'Jimmy';

  changeName() {
    this.firstname = 'Houssein';
  }
}

The syntax is simple. The target event (click) is in parentheses and the response to the event changeName() is to the right of it. The notation of having events within parentheses is new in Angular 2, where in Angular 1.x this would have looked like ng-click="changeName()".

Style Binding

Angular 2 allows us to conditionally add styles to an element with a few different ways, and one of them is by style binding.

<h1 [style.color]="isHoussein() ? 'red': 'black'">{{firstname}}</h1>
Name: <input type="text" [(ngModel)]="firstname">
<button (click)="changeName()">Change Name</button>

export class MyApp {
  firstname: string = 'Jimmy';

  changeName() {
    this.firstname = 'Houssein';
  }

  isHoussein() {
    return this.firstname === 'Houssein';
  }
}

Again, the syntax is straightforward where style is preceded by the name of a CSS style property: [style.color]. In this example, the color style property binds to the template expression, isHoussein(). With the code copied to your project, try changing the name to Houssein through the input field or by clicking the button.

Now what if we wanted to set multiple inline styles? That’s where the ngStyle directive comes in. With this, we can have multiple style properties each connected to their own condition through a key:value object.

<h1 [ngStyle]="setStyles()">{{firstname}}</h1>
Name: <input type="text" [(ngModel)]="firstname">
<button (click)="changeName()">Change Name</button>

export class App {
  firstname: string = 'Jimmy';

  changeName () {
    this.firstname = this.alternate ? 'Daniel' : 'Houssein';
    this.alternate = !this.alternate;
  }

  isHoussein() {
    return this.firstname === 'Houssein';
  }

  isDaniel() {
    return this.firstname === 'Daniel';
  }

  setStyles() {
    let styles = {
      'color':  this.isHoussein() ? 'red' : 'black',
      'font-size':  this.isDaniel() ? '3em' : '2em',
      'font-style':  this.isDaniel() || this.isHoussein() ? 'italic' : 'normal',
    };
    return styles;
  }
}

Class Binding

Similar to style binding, class binding allows you to add or remove classes based on variables or expressions.

Here’s an example of adding a conditional-based class.

<h1 [class.awesome]="isHoussein()">{{firstname}}</h1>
Name: <input type="text" [(ngModel)]="firstname">
<button (click)="changeName()">Change Name</button>

.awesome {
  color: red;
}

export class MyApp {
  firstname: string = 'Jimmy';

  changeName() {
    this.firstname = 'Houssein';
  }

  isHoussein() {
    return this.firstname === 'Houssein';
  }
}

[class.awesome] binds to the specific .awesome class when the template expression, isHoussein(), is truthy.

Now let’s see how we can use the ngClass directive to add multiple classes at the same time.

<h1 [ngClass]="setClasses()">{{firstname}}</h1>
Name: <input type="text" [(ngModel)]="firstname">
<button (click)="changeName()">Change Name</button>

.italic {
  font-style: italic;
}

.awesome {
  color: red;
}

.move {
  position: relative;
  animation:move 1s infinite;
  animation-duration: 3s;
}

@keyframes move {
    0%   {left:0px;}
    50%  {left:200px;}
    100% {left:0px;}
}

export class App {
  firstname: string = 'Jimmy';
  alternate: boolean = false;

  changeName() {
    this.firstname = this.alternate ? 'Daniel' : 'Houssein';
    this.alternate = !this.alternate;
  }

  isHoussein() {
    return this.firstname === 'Houssein';
  }

  isDaniel() {
    return this.firstname === 'Daniel';
  }

  setClasses() {
    let classes =  {
      awesome: this.isHoussein(),
      move: this.isDaniel(),
      italic: this.isHoussein() || this.isDaniel(),
    };
    return classes;
  }
}

Wrapping things up

In this post, I covered the basics of one-way and two-way data binding as well as showed how you can manipulate style properties and classes with a few different ways. Hope it proved useful and stay tuned for my next post on Angular 2.