The web browser is the most widespread deployment platform available to developers today. It’s naturally installed on every smartphone, tablet, laptop, desktop, and any other format in between. Cumulative industry growth projections have been studied over the past years approximating over 38 billion connected devices by 2025 — each one of them with a browser, and at the very least, either WiFi or a cellular connection or both. Regardless of the version or OS on them, each device will have at least one browser, which by itself is getting more features every day, some notable ones are PWA, WebVR, WebAssembly and etc.

Today, mobile accounts for 59% of all searches and 58.7% of all web traffic, according to Akamai mPulse data in July 2019. It’s the primary way people experience the web, not a second thought as it used to be 15 years ago. So given how significant mobile is, what kind of experience are we providing our visitors? Where are we going wrong?

What’s the problem?

The pitfall where many developers and businesses fall into is the assumption of having their users use their products on the latest spec high-end mobile devices over permanent internet access. We lose ourselves in the discussions of micro-optimizations so much that we forget about our core value — being user-centric.

Our delusion

In a perfect world, we would have permanent internet access and everybody would own a super-fast mobile device equipped with the latest CPU and memory hardware. Unfortunately, this is not a perfect world.

“A visualization of Time-to-Interactive highlighting how a poorly loaded experience makes the user think they can accomplish a goal, when in fact, the page hasn’t finished loading all of the code necessary for this to be true.” — Addy Osmani “The Cost Of JavaScript In 2018”:

We have to maintain users using low-end mobile devices, users who roam around the world, users who travel outside of a data coverage area, users who use a poor local WiFi in a cafe as our main target audience.

“The cost of Reddit’s JavaScript across a few different device classes (low-end, average, and high-end)” — Addy Osmani & Mathias Bynens “The cost of JavaScript in 2019”:

By adding high-end only features progressively if only a user’s network and hardware can handle it, we can deliver a fast core experience to all users and make our products accessible more than ever before.

Underestimated a core value — being user-centric

We have a tendency of getting lost in discussions on micro-optimization and of overcomplicating things too much that we forget about our main goal while delivering a product to the world.

When you overcomplicate the simplest task: %[https://www.youtube.com/embed/_sdT9t5Ha_U]

We easily become fanboys of a specific technology or framework and we almost forget what is the most important factor for our website — it’s the users!

Building a friendly, accessible and fast user experience to ALL our users should be the core of our business. When we put this goal in the center of our business and culture, what tech we use to deliver an interface becomes obsolete as long as it performs well for all our users.

So, please stop making fun of developers and websites that use jQuery to introduce interactivity to their web pages. It’s still the most popular JavaScript library ever created, and it’s used in 85.03% of desktop pages and 83.46% of mobile pages according to WebAlmanac. Although there are many Browser APIs and methods to replace most of the functionality provided by the library into a native form, such as Fetch and querySelector, it might still be a perfect fit for your next mobile web app. Take Booking.com, it still uses jQuery on their home page and it’s one of the fastest loading e-commerce websites.

Users don’t care if you use latest tech trends or a technique that helps you micro-optimise even though it’s not needed. Users care if it works and if it works fast.

Performance as a culture

The scale of the web brings us billions of connected devices and the enormous user base for online services, with the high demand for high-performance web applications. As noted many times in performance-related books, talks, and articles, speed indeed is a feature. And for some businesses, it’s the feature.

There are online services like SpeedCurve which benchmark your site against your competitors, correlate web performance with user experience, measure when your most important content renders and track the impact of web performance on your business metrics.

If you don’t bring a performance culture into the core of your business, you might declare a performance bankruptcy as Vox did a couple of years ago.

Comparison of the performance metrics of Verge and it’s competitors:

Good performance is everyone’s responsibility; from designers to developers, ops to ads, to editorial and beyond.

If we do our jobs well, everyone will be more informed about how their decisions affect the overall performance of our platform.

— Declaring performance bankruptcy By Dan Chilton

As openly came out on Vox’s statements, we all have responsibilities to bring a performance culture to the core of our organization.

PWA-first approach enforces mobile web development best practices

When you build a mobile application, there are many aspects to consider. Some are the ones you might have never considered while building a desktop website.

Gartner recently published an article where Forbes Technology Council discusses the 12 key elements that a business should be mindful of when developing a mobile app. As a PWA evangelist, it’s no surprise for me to see the section “The Advance of Progressive Web Apps” recommending considering Progressive Web Apps (PWAs) over native apps.

Consider progressive Web apps (PWAs) over native ones. PWAs are growing in popularity because they create a better user experience. They’re smaller in size, load faster and are more secure, and users can access them the same way as apps downloaded from app stores. Some of the industries already moving to cost-effective PWAs include financial services, medical manufacturing, construction and others. — John McDonald, ClearObject

What is PWA-first?

Progressive Web Apps have been around for a while now to provide native-like app experiences on both mobile and desktop platforms. And, similar to the mobile-first movement, there’s a new movement called PWA-first.

This idea helps you to build and monitor your website from day 1, caring about many user and performance-oriented features such as;

• Speed
• Offline-capability
• Progressive enhancement
• Accessibility
• Jank-free animations
• Fluid layouts

Metrics matter

Adopting the PWA-first approach helps you on putting metrics and monitoring within your core business and development workflow.

After the initial launch of your website that is optimized for mobile, it’s crucial to monitor your metrics and application performance. It brings user experience and satisfaction into your culture and helps the whole organization to further maintain those metrics by also improving them in time.

Organizational performance budgets ensure that a budget is owned by everyone rather than just being defined by one group. — Addy Osmani

To maintain a healthy mobile web strategy for your business;

• Understand performance metrics and budgets
  https://web.dev/performance-budgets-101/
• Introduce budgets for your website, either over rule-based or quantity-based metrics
  https://developers.google.com/web/tools/lighthouse/audits/budgets
  https://web.dev/your-first-performance-budget/
• Integrate lighthouse in your CI either by yourself or using a service like Calibre
• Monitor your metrics by using services like SpeedCurve
• Benchmark your site against competitors over monitoring services

Initiatives to make the web better

Google invests tremendously in making the web better by raising awareness, introducing open-source tools and libraries, helping communities with their developer relations teams, introducing web blogs and certification programs.

Some of the great examples of contributions from a community that is driven by Google engineers are;

• Web Almanac
• Web Dev Blog
• V8 Dev Blog
• Web Fundamentals
• Adaptive Loading
• RAIL Model

In addition to those awesome resources, Google also created a certification program called Mobile Web Specialist where it acknowledges developers who demonstrate mobile web development expertise. It’s one of the very few certifications in the frontend world.

You can become a Mobile Web Specialist by taking an exam on — https://developers.google.com/certification/mobile-web-specialist

Certification aside, I believe this is a great initiative to raise awareness for building a healthy web. It’s a token for people to show that they care about a healthy web and they’ve skills and expertise to make the web better.

How can we help you help yourself?

We’ve built a 5-days training program called Mobile Web Specialist bootcamp at LINKIT to help developers build great mobile websites, focusing on web fundamentals and technology rather than frameworks and libraries.

It covers the topics on the study guide of Mobile Web Specialist certification and teaches participants modern web development practices with a hands-on heavy agenda.

It aims to have participants feel confident with building great mobile website experiences at the end as well as helping them get the Mobile Web Specialist certification of Google.

We help businesses — note to employers

We help managers like you to bring cultural changes to your business. By investing in your employees taking this training, you make sure you’re right on track on building a great mobile strategy and production for your business.

With investing in PWA-first, you de-risk your business by making sure that it can reach the largest number of people with the least amount of friction. Some notable case studies showing a direct positive impact on business objectives are;

• Pinterest reduced their JavaScript bundles from 2.5MB to < 200KB and Time-to-Interactive reduced from 23s to 5.6s. Revenue went up 44%, sign-ups are up 753%, weekly active users on mobile web are up 103%.
• AutoTrader reduced their JavaScript bundle sizes by 56% and reduced Time-to-Interactive for their pages by ~50%.
• Nikkei reduced their JavaScript bundle size by 43% and Time-to-Interactive improved by 14s.
• More case studies available at Google Developers blog, and PWAStats

We help developers — note to employees

We help developers like you to focus on business objectives and user experience rather than tech trends. We put web fundamentals and native browser functionality on top of frameworks and libraries so it’s up to you to choose which direction to go.

By investing in yourself with attending to Mobile Web Specialist training of LINKIT, you make sure you keep up with the best practices for building a great website experience satisfying all your visitors from around the world.

We create an alumni community where we exchange ideas, ask questions to each other, share resources that we find useful on the topic from and to a community built by like-minded people, like yourself.

Feel free to DM me on Twitter or LinkedIn if you’ve any questions or remarks about the certification or our training program.

We love the web, we bet on the web and let’s make it better all together!

The referred project and examples in this article are based on node.js, eslint, TypeScript, Jest, semantic-release and npm stack. The principles are the same for any other tech stack, so you should be able to use a similar flow with your own project as well.

In this article, we’re focusing on building 2 pipelines;

• CI — builds a TypeScript node.js project, lints the code and runs tests on the project
• Release — builds the project and deploys an npm package to npm repository with semantic-release

Whether you’re migrating from Travis CI to GitHub actions or migrating from CircleCI to GitHub actions or starting a new open source project on GitHub, this article should give you a head start on your CI/CD journey.

About GitHub actions

GitHub announced its own continuous integration service as an alternative to services out there like Travis CI, Circle CI and others.

It’s free for open source projects as Travis CI and Circle CI are, and it’s well integrated with GitHub ecosystem.

GitHub introduces a few concepts in their continuous integration context. Core concepts such as workflows, jobs, steps, actions, runners, events and artifacts are documented on GitHub actions documentation.

I’d like to summarize the concepts that we will use on our CI and CD pipelines for a better understanding of the ecosystem we’re in.

Workflows

Workflows are basically pipelines, which can build, test, package, release, or deploy any project on GitHub. They are made up of one or more jobs and can be scheduled or activated by an event. Each workflow must be declared by a YAML file under .github/workflows folder in your repository.

For example; ci.yml for a CI workflow, or release.yml for a release workflow.

Jobs

Jobs are basically tasks made up of steps. A fresh virtual environment is created for each job. Dependencies and configurations of a job are declared on the workflow file.

For example; build job for compiling your project, or test job for executing unit/integration tests.

Actions

Actions are basically tasks that you combine as steps to create a job. They are the smallest portable building blocks of a workflow. It provides a flexible architecture as you can create your own actions based on docker images, use actions shared by the open source community, and customize public actions. Actions must be included as a step in order to use within a workflow.

For example; actions/checkout action on a step for checking out your project, or actions/setup-node action on a step to setup node dependency.

Creating an integration workflow — CI

In our context, we are going to create an integration workflow with the goal of;

1. Installation of our project dependencies to install and setup our toolset for further steps.
2. Compilation of our TypeScript code to assure we don’t have any compilation issues.
3. Linting of our TypeScript code with eslint to assure we maintain a specific code quality.
4. Testing of our functionality with unit and integration tests with Jest to assure our product quality.

In order to accomplish our goal, we need to create a new workflow file under .github/workflows folder of our repository. Let's call it CI.yml and create this file with the following content.

name: CI

on: [push]

jobs:
  test:
    name: Test on node ${{ matrix.node }} and ${{ matrix.os }}

    runs-on: ${{ matrix.os }}

    strategy:
      matrix:
        node: [8, 10, 12]
        os: [ubuntu-latest, macOS-latest, windows-latest]

    steps:
      - uses: actions/checkout@v1
      - name: Use node ${{ matrix.node }}
        uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node }}
          registry-url: https://registry.npmjs.org
      - name: install
        run: npm install
      - name: lint
        run: npm run lint
      - name: build
        run: npm run build
      - name: test
        run: npm test

As you might have noticed, I set specific versions to the actions I’m using — actions/checkout@v1. This is a good idea when you deal with a tool on beta stage as it might introduce breaking changes otherwise.

A demonstration of a CI run of pwa-asset-generator — you can see it in detail here

It introduces node and OS matrixes for the pipeline, which means that test job will run on 3 x 3 = 9 environments, namely;

• Test on node 8 and ubuntu-latest
• Test on node 8 and macOS-latest
• Test on node 8 and windows-latest
• Test on node 10 and ubuntu-latest
• Test on node 10 and macOS-latest
• Test on node 10 and windows-latest
• Test on node 12 and ubuntu-latest
• Test on node 12 and macOS-latest
• Test on node 12 and windows-latest

See the full list of environments that are supported by GitHub actions here: https://help.github.com/en/articles/virtual-environments-for-github-actions

The steps on test job can also be individual jobs but good to acknowledge that it will take more time to execute as we need to spinoff a new environment and install dependencies for each job.

You can also schedule your runs based on a cron, for instance nightly builds. To read more about all other configuration options on a workflow, visit Configuring a workflow documentation.

Creating an automated release workflow with semantic release— CD

I’m a big fan of one-button deployments aka continuous deployment. It’s quite easy to setup a CD pipeline for node.js projects that are deployed to npm with the use of semantic-release.

In this context, we are going to create a release workflow with the goal of;

1. Installation of our project dependencies to install and setup our toolset for further steps.
2. Compilation of our TypeScript code to assure we are ready with our build artifact — dist folder in our context.
3. Release of our artifact with semantic-release to automate releases for each code push on our master branch.

In order to accomplish our goal, we need to create a new workflow file under .github/workflows folder of our repository. Let's call it release.yml and create this file with the following content.

name: Release

on:
  push:
    branches:
      - master

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: 12
          registry-url: https://registry.npmjs.org
      - run: npm install
      - run: npm run build
      - run: npx semantic-release
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          GH_TOKEN: ${{ secrets.GH_TOKEN }}

A demonstration of a release run on pwa-asset-generator — you can see it here in detail

Setting up secrets

As you might have noticed, there are secret environment variables set for semantic-release, which are required for deploying our package to npm and creating automated chore commits on our GitHub repo.

You can set those secrets on your GitHub settings and use them in your workflow files with this format: ${{ secrets.SECRET_NAME }}. To setup secrets;

1. Navigate to the Settings of your GitHub repo and click on the Secrets menu on the left sidebar. Then click on Add a new secret link.

Put in a name for your secret, which you’ll later use as environment variable on your workflow file.

2. Repeat the same for both NPM_TOKEN and GH_TOKEN secrets, which both are required by semantic-release for automated release on npm and administration in your repo on GitHub.

You can create your npm token on your npm console: https://www.npmjs.com/settings/username/tokens

You can create your GitHub token on your GitHub profile: https://github.com/settings/tokens

Note that a typical semantic-release setup requires these permissions on GitHub token: read:org, read:packages, repo, user:email, write:packages, write:repo_hook

Skipping workflow runs for chore commits

Semantic release library automates a series of chore commits after each successful release. Those commits are automated by release-notes-generator and github plugins but not limited to — see the full list of plugins.

See all the commits tagged with chore in pwa-asset-generator

After having the chore commits in the repo, GitHub actions runs an additional workflow run as any commit should trigger a run on CI workflow.

However, having an additional workflow run is not necessary and it’s a good practice to skip CI runs caused by any of chore commits. As you might noticed above, chore commit messages include [skip ci] text, added by semantic release for each chore commit.

We can configure GitHub actions to skip runs for all the chore commits including [skip ci] message by adding the following configuration;

name: Release

on:
  push:
    branches:
      - master

jobs:
  prepare:
    runs-on: ubuntu-latest
    if: "! contains(github.event.head_commit.message, '[skip ci]')"
    steps:
      - run: echo "${{ github.event.head_commit.message }}"

  publish:
    needs: prepare
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v1
      - uses: actions/setup-node@v1
        with:
          node-version: 12
          registry-url: https://registry.npmjs.org
      - run: npm install
      - run: npm run build
      - run: npx semantic-release
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
          GH_TOKEN: ${{ secrets.GH_TOKEN }}

The configuration example above is for release workflow and you can use the same approach for your CI workflow as well.

Adding the status badge of your workflow

Now it’s time for the fun part. Every open source project deserves a badge/shield to show their users that it’s well maintained. One of the most popular badges for an open source project is the build status badge.

You can find many available shields for various vendors here: https://shields.io/category/build

GitHub actions provide their own status badges for each workflow. As you can see on my project pwa-asset-generator on both GitHub and npm, it uses CI workflow badge to show users that all integration tests are passing.

Demonstration of GitHub actions CI workflow badge on pwa-asset-generator readme:

You can use an SVG image link on your project to display the badge of your GitHub actions workflow with this pattern:

https://github.com/{username}/{repo}/workflows/{workflowname}/badge.svg

The SVG link displaying your workflow status with the name of your workflow:

Here’s the markdown for badge only, which you can use on the README file of your project;

![Build Status](https://github.com/{username}/{repo}/workflows/{workflowname}/badge.svg)

Here’s the markdown for badge and link to your actions together;

[![Build Status](https://github.com/{username}/{repo}/workflows/{workflowname}/badge.svg)](https://github.com/{username}/{repo}/actions)

GitHub actions currently has an issue with displaying latest workflow status on your status badge if latest run is skipped.

I reported this issue to GitHub. If you’re like me and think that status badge should display status of the latest run before the skipped runs, feel free to give kudos (upvote) to the issue.

Congratulations!

You made it! Now you have an automated integration and deployment pipeline for your project running on GitHub actions.

You can drop me a message on Twitter if you need any help on your CI/CD setup. Cheers!

It automatically generates splash screen and icon images for your Progressive Web App in order to provide native-like user experiences on multiple platforms. It also updates your index.html and manifest.json files to declare generated assets to your PWA.

I’d like to get into details of my motivation for building such a library along with some advanced usage examples in this article.

A basic usage demo of pwa-asset-generator:

I’ll explain why such a library is needed and how it’s compared to some other existing options of generating assets for your PWA on the following chapters.

Feel free to jump to the final chapter of the article ⏬ to see features and advanced usage examples of the library.

Why do we need such a library anyway?

When you build a PWA with the goal of providing native-like user experiences on multiple platforms and stores, you need to meet the criteria of those platforms and stores with your PWA assets; icons and splash screens. Such criteria are;

• Google’s Android platform respects Web App Manifest API specs and it expects you to provide at least 2 icon sizes in your manifest file — https://developers.google.com/web/fundamentals/web-app-manifest/#icons
• As it’s noted on Microsoft docs, your PWA has to meet specific image criteria declared on Web App Manifest in order to be automatically packaged for Microsoft Store — https://docs.microsoft.com/en-us/microsoft-edge/progressive-web-apps/get-started#web-app-manifest

Once you use icons with required sizes as part of Web App Manifest API, you don’t need to provide additional splash screen images for above platforms. They are automatically generated for you.

Criteria for iOS

Complicated. Currently, iOS doesn’t support Web App Manifest API specs, although the spec is in development— track the progress here. It’s also not clear yet if Apple will change its approach for displaying splash screens during standards implementation, as splash screens are not part of Web App Manifest specs. So far, the only way to setup icons and splash screens for your PWA on iOS is, adding special HTML tags.

A special HTML link tag with rel apple-touch-icon is required to provide icons for your PWA when it's added to the user’s home screen. Read more about it on Apple's Icon Guidelines and Safari Web Content Guide.

Example icon specs from Apple’s Icon Guidelines:

Another special HTML link tag with rel apple-touch-startup-image is required if you also would like to provide splash screens for your PWA. iOS will display those screens when your PWA is being opened as well as when it's in the background. So far so good!

But, there’s a catch here: you need to create a splash screen image for each and every resolution on Apple’s Launch Screen Guidelines and add an HTML tag with media attribute for each device resolution and orientation 🙀! Unfortunately, this requirement is not documented on Safari Web Content Guide sufficiently.

Example link tag for just one resolution & orientation pair;

<link rel="apple-touch-startup-image" href="temp/apple-splash-2048-2732.png" media="(device-width: 1024px) and (device-height: 1366px) and (-webkit-device-pixel-ratio: 2) and (orientation: portrait)">

Example splash screen specs from Apple’s Launch Screen Guidelines

💡 Creating icon and splash screen images for all the platforms, maintaining sizes and quality for all and adding HTML tags for each image can be overwhelming. So, why not automate it? 🤖

Drawbacks of existing solutions

When I decided to build such a CLI library, there were already a couple of options out there to generate assets for PWAs and meta associated with them. They might as well be a good fit for your needs but I think it’s wise to get to know the drawbacks of them when deciding what to use.

Some of the drawbacks that I noticed when I used them are;

Runtime dependency

One of the options to generate and use PWA assets is using PWACompat. I think it’s a good option to maintain a standard splash screen look and feel across platforms. However, it uses an approach to generate PWA images on runtime (iOS) and store them in the session storage of your browser. Keep in mind that, this approach not only affects the initialization performance of your PWA, it also takes over the ownership of your manifest.json file and your assets.

Brings maintenance costs

Some other options to generate and use PWA assets are online tools like AppScope splash screen generator or PWABuilder. These tools individually generate either icons OR splash screens and there isn’t any online tool that generates both asset types. They also come with maintenance costs such as;

• Unzipping content and re-locating the assets
• Updating manifest.json or index.html files manually
• Keeping an eye on the standards and guidelines to keep your PWA compatible with all device types and platforms

And, doing this manual work again and again.

Difficult to automate

Another drawback of using online tools is that they are difficult to automate. An ideal scenario of keeping your PWA assets up to date and compatible with all platforms in an automated way would be integrating pwa-asset-generator to your build steps on your favorite CI. It can generate all the assets and update your index.html and manifest.json files with associated meta based on the latest platform specifications.

Lacks flexibility and ownership on the content

You’re not in control of how your assets are generated. None of the existing solutions provide full control of how your assets are generated. PWACompat doesn’t provide any control at all, it automatically generates all splash screens in the same form. And, online tools provide limited customization options when you generate your assets. pwa-asset-generator gives you full control of your assets via HTML inputs. I will describe this in detail in the next chapter.

Features and usage of the lib

PWA Asset Generator automates the image generation in a creative way. Having Puppeteer at its core enables lots of possibilities.

— Generates both icons and splash screens with optional --icon-only --splash-only --landscape-only and --portrait-only flags ✨

— Updates your manifest.json and index.html files automatically for declaring generated image assets 🙌

— Scrapes latest specs from Apple Human Interface guidelines website via Puppeteer to make your PWA ready for all/recent iOS devices out there 🤖

• Supports offline mode and uses static spec data when things go wrong with scraping 📴
• Updates static spec data before each release automatically and monitors spec changes everyday 🔄

— Uses the Chrome browser as it’s a canvas of your fav image editor. It uses a shell HTML file as an artboard and centers your logo before taking screenshots for each resolution via Puppeteer 🤖

— You can provide your source in multiple formats; a local image file, a local HTML file, a remote image or HTML file 🙌

• When it’s an image source, it is centered over the background option you provide 🌅
• When it’s an HTML source, you can go as creative as you like; position your logo, use SVG filters, use variable fonts, use gradient backgrounds, use typography and etc. Your HTML file is rendered on Chrome before taking screenshots for each resolution 🎨

— It uses puppeteer-core instead of puppeteer and only installs Chromium if it doesn’t exist on the system. Saves waste of ~110–150mb of disk space and many seconds from the world per each user 🌎️️⚡️

— Supports dark mode splash screens on iOS! So, you can provide both light 🌕 and dark 🌚 splash screen images to differentiate your apps look & feel based on user preference 🌙

Examples

1. Basic usage with local PNG input, skips scraping specs, generating both splash screens and icons;

npx pwa-asset-generator ./img/logo.png --background "#ababab" --scrape false

2. Advanced usage with remote SVG input, using a custom gradient background 🏳️‍🌈, generating icons only;

npx pwa-asset-generator https://animejs.com/documentation/assets/img/icons/icon-github.svg ./temp -b "linear-gradient(180deg, #f00000, #f00000 16.67%, #ff8000 16.67%, #ff8000 33.33%, #ffff00 33.33%, #ffff00 50%, #007940 50%, #007940 66.67%, #4040ff 66.67%, #4040ff 83.33%, #a000c0 83.33%, #a000c0) fixed" --icon-only

💡 One can introduce a build step on CI to automate differentiating the branding of a PWA on special occasions. Wouldn’t it be awesome?

3. Advanced usage with custom HTML input, using background tile and custom variable web-font in it, generating splash screens only, outputting JPEG file type with 70% quality, with code output saved to your PWA’s index.html file;

# The local nyan.html can be a remote url as well  
# npx pwa-asset-generator https://ny.an/nyan.html
npx pwa-asset-generator nyan.html ./src/app/temp --splash-only --type=jpeg --quality=70 --index ./src/app/index.html

If you’re curious to see how such an HTML is built, here’s the Gist.

💡 When HTML input is used, you gain full control on your assets 👩‍💻 You can use any sort of web technology to render the content of your assets. Some might include but not limited to SVG filters, css media queries, variable fonts, css image filters, gradient backgrounds, and image tiles 👩‍🎨

4. Generating both light and dark mode splash screens for iOS, outputting JPEG file type with 80% quality, with code output saved to your PWA’s index.html file;

npx pwa-asset-generator light-logo.svg ./assets --dark-mode --background dimgrey --splash-only --type jpeg --quality 80 --index ./src/app/index.html

npx pwa-asset-generator dark-logo.svg ./assets --background lightgray --splash-only --type jpeg --quality 80 --index ./src/app/index.html

Video demonstration of dark mode splash screens on iOS:

BONUS: Under the hood

For curious minds reading up to this point, I’d like to share a simple yet powerful concept that library uses under the hood.

As I mentioned earlier, using Puppeteer under the hood opens a door of possibilities. A key feature of Puppeteer that pwa-asset-generator uses, is its screenshot API.

Puppeteer allows saving screenshots in both PNG and JPEG file types with optional compression possibility for JPEG images.

Every time you execute a command with pwa-asset-generator, library scrapes latest iOS specs from 2 sources. Then it opens new tabs rendering the content of shell HTML, based on CLI parameters provided. Here’s the shell HTML content;

<!DOCTYPE html>  
<html>  
<head>  
  <meta name="viewport" content="width=device-width, initial-scale=1">  
  <style>  
    body {  
      margin: 0;  
      background: --background;  
      height: 100vh;  
      padding: --padding;  
      box-sizing: border-box;  
    }  
    img {  
      width: 100%;  
      height: 100%;  
      margin: 0 auto;  
      object-fit: contain;      
    }  
  </style>  
</head>  
<body>  
<img src="--image-input">  
</body>  
</html>

It opens a new browser tab that renders shell HTML file contents via Puppeteer for each icon and splash screen size, and finally saves a screenshot of each.

// You can see the complete source here: https://github.com/onderceylan/pwa-asset-generator/blob/master/src/helpers/puppets.ts

// You can see the complete source here: https://github.com/onderceylan/pwa-asset-generator/blob/master/src/helpers/puppets.ts
const saveImages = async (
  imageList: Image[],
  source: string,
  output: string,
  options: Options,
  browser: Browser,
): Promise<SavedImage[]> => {
  let address: string;
  let shellHtml: string;

  const logger = preLogger(saveImages.name, options);
  logger.log('Initialising puppeteer to take screenshots', '🤖');

  if (canNavigateTo(source)) {
    address = await url.getAddress(source, options);
  } else {
    shellHtml = await url.getShellHtml(source, options);
  }

  return Promise.all(
    imageList.map(async ({ name, width, height, scaleFactor, orientation }) => {
      const { type, quality } = options;
      const path = file.getImageSavePath(name, output, type);

      try {
        const page = await browser.newPage();
        await page.setViewport({ width, height });

        if (address) {
          await page.goto(address);
        } else {
          await page.setContent(shellHtml);
        }

        await page.screenshot({
          path,
          omitBackground: !options.opaque,
          type: options.type,
          ...(type !== 'png' ? { quality } : {}),
        });

        await page.close();

        logger.success(`Saved image ${name}`);

        return { name, width, height, scaleFactor, path, orientation };
      } catch (e) {
        logger.error(e.message);
        throw Error(`Failed to save image ${name}`);
      }
    }),
  );
};

I was inspired by this blog post initially for the idea of saving screenshots of a resized responsive web page, thanks for the inspiration Dominik!

⚡️ Unlike Puppeteer, pwa-asset-generator uses system browser first approach using chrome-launcher with puppeteer-core and it only installs chromium if it’s not installed on execution environment.

Since the library uses Puppeteer in headless mode, you don’t see what’s happening under the hood. To make it visible, here’s a demonstration of the process, by disabling the headless mode in Puppeteer launch options;

Support

If you like the library, I appreciate your star on GitHub and your like/retweet and feedback on Twitter. If you’re a blogger too, it’d be awesome to see a reference to it on your blogs related to PWAs.

If you enjoyed my article, follow me here and on Twitter to subscribe to my future posts and projects! Cheers!

Being a Progressive Web App evangelist, it’s no surprise that one of my favourite ng schematics is @angular/pwa. This schematic gives you a head start on your PWA development journey. However, you need to do more on your app to create the best experiences for your users on multiple mobile platforms.

This tutorial will cover how to build, optimise and host your PWA to provide native-like app experiences on the production environment. It provides guidelines for best practices and platform optimisations. In addition to that, your PWA will score 💯 on Lighthouse PWA audit after following the guidelines and tips described in this article.

Before going forward, keep in mind that this is a tutorial and you might want to keep track of your progress. I host international workshops with almost the same content as in this article. That’s why I created a repo for the workshop material on GitHub. You can do the workshop yourself remotely if you wish 👇

If you like the workshop, I appreciate your star on GitHub. Here we go!

1. Adding @angular/pwa schematic to an Angular app

The first thing you need to do -on your brand new or existing Angular app to build a Progressive Web App - is adding @angular/pwa schematic to your app.

You can do this by simply running add command on your Angular CLI.

ng add @angular/pwa

💡 TIP — Use `npx ng` command in your Angular project without installing a global @angular/cli package on your system.

Adding @angular/pwa schematic will create following files on your project, which we will dive into later on.

ngsw-config.json  
src/assets/icons/icon-128x128.png  
src/assets/icons/icon-144x144.png  
src/assets/icons/icon-152x152.png  
src/assets/icons/icon-192x192.png  
src/assets/icons/icon-384x384.png  
src/assets/icons/icon-512x512.png  
src/assets/icons/icon-72x72.png  
src/assets/icons/icon-96x96.png  
src/manifest.json

It will also tweak your angular.json, index.html and app.module.ts files accordingly.

2. Changing Web App Manifest file — manifest.json

The web app manifest is a simple JSON file that tells the browser about your web application and how it should behave when ‘installed’ on the user’s mobile device or desktop. Having a manifest is required by Chrome to show the Add to Home Screen prompt.

A typical manifest file includes information about the app name, icons it should use, the start_url it should start at when launched, and more.

— Web App Manifest on Google Developers Portal

Use Chrome DevTools’ Application tab to inspect your app’s manifest.json file

2.1 Adding description

One of the improvement points that I see on the manifest.json file, which was generated by @angular/pwa schematic, is the addition of description field. Description field is documented on both W3C Web App Manifest spec and MDN.

{  
  "description": "My Fancy PWA is a dummy Angular app which demonstrates a PWA's behaviour on different platforms."  
}

2.2 Tracking the start url

It is also a good practice to add a query string to the end of the start_url field in manifest.json file to track how often your installed app is launched from users’ home screen.

{  
  "start_url": `"/?utm_source=a2hs"  
}

💡 TIP — Providing a name, description and an app icon that is at least 512 x 512 pixels will help your app to be automatically indexed and packaged on Microsoft Store.

Example of a full manifest.json file that I use on one of my PWAs:

{
  "name": "ITNEXT Summit 2018",
  "short_name": "ITNEXT",
  "description": "Be the best explorer in next-gen technologies. Experience use-cases, howtos and best-practices with latest frontend and backend technologies, network and security, engineering and low-code development with OutSystems.",
  "theme_color": "#ffffff",
  "background_color": "#ffffff",
  "display": "standalone",
  "orientation": "portrait",
  "scope": "/",
  "start_url": "/?utm_source=itnext_pwa_a2hs",
  "icons": [
    {
      "src": "assets/icons/icon-72x72.png",
      "sizes": "72x72",
      "type": "image/png"
    },
    {
      "src": "assets/icons/icon-96x96.png",
      "sizes": "96x96",
      "type": "image/png"
    },
    {
      "src": "assets/icons/icon-128x128.png",
      "sizes": "128x128",
      "type": "image/png"
    },
    {
      "src": "assets/icons/icon-144x144.png",
      "sizes": "144x144",
      "type": "image/png"
    },
    {
      "src": "assets/icons/icon-152x152.png",
      "sizes": "152x152",
      "type": "image/png"
    },
    {
      "src": "assets/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "assets/icons/icon-384x384.png",
      "sizes": "384x384",
      "type": "image/png"
    },
    {
      "src": "assets/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "gcm_sender_id": "103953800507"
}

3. Displaying an A2HS guideline

Google Chrome automatically detects a PWA on Android systems and if the site meets the add to home screen criteria, it shows an install banner or mini info bar to the user to allow them adding it to their home screen.

Add to Home Screen dialog on Android

💡 TIP — short_name field in your manifest.json will represent your PWA’s name when it’s added to a home screen. Additionally, name field will be used on Add to Home Screen prompt on Android!

Such functionality does not exist on iOS. But, luckily we can build our own UX to guide users towards the required taps to help them add your app to their home screens.

It can be a good old popup;

A popup to guide users —Source: https://dockyard.com/blog/2017/09/27/encouraging-pwa-installation-on-ios

Or, even better; a mini-info bar which mimics Chrome’s behaviour on Android platforms to create a uniform experience across platforms.

A mini-info bar like guidance — Source: https://www.netguru.com/codestories/few-tips-that-will-make-your-pwa-on-ios-feel-like-native

For example, I used a bit of code on one of my PWAs to introduce this behaviour.

import { get, set } from 'idb-keyval';
import { ToastController } from '@ionic/angular';
async showIosInstallBanner() {
  // Detects if device is on iOS
  const isIos = () => {
    const userAgent = window.navigator.userAgent.toLowerCase();
    return /iphone|ipad|ipod/.test(userAgent);
  };
  // Detects if device is in standalone mode
  const isInStandaloneMode = () => ('standalone' in window.navigator) && window.navigator.standalone;

  // Show the banner once
  const isBannerShown = await get('isBannerShown');

  // Checks if it should display install popup notification
  if (isIos() && !isInStandaloneMode() && isBannerShown === undefined) {
    const toast = await this.toastController.create({
      showCloseButton: true,
      closeButtonText: 'OK',
      cssClass: 'custom-toast',
      position: 'bottom',
      message: `To install the app, tap "Share" icon below and select "Add to Home Screen".`,
    });
    toast.present();
    set('isBannerShown', true);
  }
}

4. Adding meta tags for platform optimisation

WebKit is the web browser engine used by Safari, Mail, App Store, and many other apps on macOS, iOS, and Linux — https://webkit.org/

Although many browsers adopted the Web App Manifest spec, WebKit (specifically, Mobile Safari on iOS) currently uses custom non-standards track meta tag implementations.

Because of that, Apple’s iOS doesn’t create a splash screen or an app icon for a PWA automatically the same way that Google’s Android does based on the app’s manifest file. This prevents your PWA to provide native-app-like experience.

💡 TIP — Keep an eye on WebKit Feature Status for tracking the progress of the implementation of web standards. For instance; once Web App Manifest specs is implemented on WebKit, you won’t need to use custom meta tags anymore. Track the progress here: https://webkit.org/status/#?search=manifest

Fortunately, there is a workaround to configure app icons, splash screens and status bar of your PWA on iOS platform. The workaround is adding custom meta tags to your app’s index.html file!

4.1 Adding meta tags for app icons on iOS

As discussed above, iOS does not recognize the app icons that you’ve put in your manifest file. That’s why you need to add meta tags to your index.html file to optimise your app and its icons for iOS.

The following example demonstrates specifying various sizes for most common iOS devices:

<link rel="apple-touch-icon" href="touch-icon-iphone.png">
<link rel="apple-touch-icon" sizes="152x152" href="touch-icon-ipad.png">
<link rel="apple-touch-icon" sizes="180x180" href="touch-icon-iphone-retina.png">
<link rel="apple-touch-icon" sizes="167x167" href="touch-icon-ipad-retina.png">

You can read more about this topic on Apple’s Safari Web Content Guide.

4.2 Adding meta tags for splash screens on iOS

In order to add splash screen to your PWA on iOS, you must add a meta tag that points out an image for a specific resolution. If the size of an image in the meta tag matches with the device’s resolution, iOS will show the image as a splash screen.

Apple uses a custom link with a rel called apple-touch-startup-image to support splash screens for an app added to iOS home screen, as you can see it here. You also need to set apple-mobile-web-app-capable meta in order to bring the support for splash screens.

<meta name="apple-mobile-web-app-capable" content="yes">  
<link rel="apple-touch-startup-image" href="/launch.png">

You need to create static images in different sizes for different devices. Here’s a list of devices and their resolutions:

Static launch screen images — Apple Human Interface Guidelines

This is an example of some of the meta tags I have in my PWAs index.html file:

<link href="/assets/splash/iphone5\_splash.png" media="(device-width: 320px) and (device-height: 568px) and (-webkit-device-pixel-ratio: 2)" rel="apple-touch-startup-image">
<link href="/assets/splash/iphone6\_splash.png" media="(device-width: 375px) and (device-height: 667px) and (-webkit-device-pixel-ratio: 2)" rel="apple-touch-startup-image">
<link href="/assets/splash/iphonex\_splash.png" media="(device-width: 375px) and (device-height: 812px) and (-webkit-device-pixel-ratio: 3)" rel="apple-touch-startup-image">

💡 TIP — Use an automated tool to generate your images and their corresponding html codes. Here’s an open source library that I built just for this purpose: https://github.com/onderceylan/pwa-asset-generator

npx `pwa-asset-generator https://github.com/onderceylan/pwa-asset-generator/blob/master/static/logo.png -b "linear-gradient(to right, #fa709a 0%, #fee140 100%)"`

Generate splash screen and icon images and corresponding HTML tags automatically via pwa-asset-generator

4.3 Adding meta tags for the status bar on iOS

You can customize iOS status bar of your PWA by using apple-mobile-web-app-status-bar-style meta tag in your index.html file. This meta tag has no effect unless you specify full-screen mode aka standalone for your PWA.

<meta name="apple-mobile-web-app-status-bar-style" content="white">

View of the status bars; black-translucent*, **white*, and *black*

Apple only supports 3 options for the content attribute of the meta tag with no further customisation possibility. The options are;

• white — displays a white status bar with black text and symbols. default value has the same effect as white but I prefer white over that. It’s less confusing as default being non-default behaviour! 🤯
• black — displays a black status bar and white text and symbols. This is the default behaviour of a PWA on iOS, when this meta tag is not in place.
• black-translucent — displays a white text and symbols, with status bar using the same background color of your app’s body element.

4.4 Meta tags for social share

Progressive Web Apps are accessible via web by nature. This means that you can just share a link to your PWA on social media or instant messaging services.

For the convenience of your users who shares your app with their network, I recommend creating a nice preview of your app by adding Open Graph Protocol meta tags to your PWA.

A preview of your app’s link on Twitter with the Open Graph meta tags provided

Here’s an example of required meta tags to provide a nice user experience:

<meta property="og:title" content="ITNEXT Summit 2018 PWA">  
<meta property="og:description" content="Check out the PWA of ITNEXT Summit 2018. It rocks!">  
<meta property="og:image" content="https://itnext-summit-2018.firebaseapp.com/assets/img/social-share.png">  
<meta property="og:url" content="https://itnext-summit-2018.firebaseapp.com">  
<meta name="twitter:card" content="summary_large_image">

Furthermore, you can introduce even more optimisations to your PWA to customize user experience on iOS.

Please visit Safari HTML reference for the full list of Apple specific meta tags: https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html

Apart from using the meta tags, some additional optimisations can be done by using simple CSS tweaks. Such as;

• Disabling selection
• Disabling highlighting
• Disabling callouts
• Enabling tab effects

Read more on those here:

5. Configuring ngsw-config.json — Angular Service Worker

When you add @angular/pwa schematic, Angular’s ServiceWorkerModule is injected to your app.module.ts file. This module registers your automatically generated service worker file — ngsw-worker.js which is built by ng cli during the production build.

You can refer to Angular docs for service worker configuration to understand the design and possible options for your configuration.

5.1 Data groups

Unlike asset resources, data requests are not versioned along with the app. They’re cached according to manually-configured policies that are more useful for situations such as API requests and other data dependencies.

What I would like to stress here is the caching strategies for data resources. Angular service worker is designed with brevity in mind, therefore it provides 2 caching strategies.

Caching strategy: performance

Suitable for resources that don’t change often; for example, user avatar images. — Angular docs

Performance is a cache-first strategy

performance, the default, optimizes for responses that are as fast as possible. If a resource exists in the cache, the cached version is used. This allows for some staleness, depending on the maxAge, in exchange for better performance. This is suitable for resources that don't change often; for example, user avatar images.

Caching strategy: freshness

Useful for resources that change frequently; for example, account balances. — Angular docs

Freshness is a network-first strategy

freshness optimizes for currency of data, preferentially fetching requested data from the network. Only if the network times out, according to timeout, does the request fall back to the cache.

"dataGroups": [
    {
      "name": "from-api",
      "version": 2,
      "urls": ["/data/data.json"], // or ["/dashboard", "/user"]
      "cacheConfig": {
        "strategy": "performance",
        "maxSize": 10,
        "maxAge": "1h",
        "timeout": "3s"
      }
    }
  ]

With the example above, data from APIs or a static json file received will be cached with a freshness strategy for a maximum of 10 responses, maximum cache age of 1 hour, and a timeout of 3 seconds, after which the result will fallback to the cache. Freshness is a network-first strategy and alternatively, you can use performance as the strategy for a cache-first strategy.

💡 TIP — Increase version field in dataGroups to invalidate your cache of data resources when your data source has been updated in backwards-incompatible way. A new version of the app may not be compatible with the old data format.

5.2 Asset groups

Assets are resources that are part of the app version that update along with the app. They can include resources loaded from the page’s origin as well as third-party resources loaded from CDNs and other external URLs.

Depending on the policy by which they are cached, you can introduce either lazy or prefetch strategy on each of your asset group. Resources on service worker configuration accept glob-like patterns that match a number of files, like;

"assetGroups": [
    {
      "name": "shell",
      "installMode": "prefetch",
      "updateMode": "prefetch",
      "resources": {
        "files": [
          "/favicon.ico",
          "/index.html",
          "/*.css",
          "/vendor.*.js",
          "/main.*.js",
          "/polyfills.*.js",
          "/runtime.*.js",
          "/*.js",
          "!/*-sw.js"
        ]
      }
    },
    {
      "name": "assets",
      "installMode": "lazy",
      "updateMode": "prefetch",
      "resources": {
        "files": [
          "/assets/**",
          "/svg/**"
        ],
        "urls": [
          "https://fonts.googleapis.com/**"
        ]
      }
    }
  ]

For resources already in the cache, the updateMode determines the caching behaviour when a new version of the app is discovered. Any resources in the group that have changed since the previous version are updated in accordance with updateMode. Angular service worker will automatically handle updates of your assets when there’s a new service worker version for your app.

💡 TIP — When you use a caching strategy, you must exclude the resources that you’d like to keep fresh. Such as additional service worker files that your app might use.

Following example of a full ngsw-config.json file demonstrates asset groups, data groups, app data and a glob for excluding additional service workers:

{
  "index": "/index.html",
  "appData": {
    "version": "1.1.0",
    "changelog": "Added better resource caching"
  },
  "assetGroups": [
    {
      "name": "shell",
      "installMode": "prefetch",
      "updateMode": "prefetch",
      "resources": {
        "files": [
          "/favicon.ico",
          "/index.html",
          "/*.css",
          "/vendor.*.js",
          "/main.*.js",
          "/polyfills.*.js",
          "/runtime.*.js",
          "/*.js",
          "!/*-sw.js"
        ]
      }
    },
    {
      "name": "assets",
      "installMode": "lazy",
      "updateMode": "prefetch",
      "resources": {
        "files": [
          "/assets/**",
          "/svg/**"
        ],
        "urls": [
          "https://fonts.googleapis.com/**"
        ]
      }
    }
  ],
  "dataGroups": [
    {
      "name": "from-static",
      "version": 1,
      "urls": ["/data/data.json"],
      "cacheConfig": {
        "strategy": "performance",
        "maxSize": 10,
        "maxAge": "1d",
        "timeout": "5s"
      }
    },
    {
      "name": "from-api",
      "version": 2,
      "urls": ["/dashboard", "/user"],
      "cacheConfig": {
        "strategy": "freshness",
        "maxSize": 15,
        "maxAge": "1h",
        "timeout": "3s"
      }
    }
  ]
}

6. Configuring angular.json for static assets

Angular Console logo, a GUI for Angular CLI — https://angularconsole.com

One of the most important points to pay attention while building a PWA with Angular is the configuration of static assets. You need to be aware of your build configuration and its output on production build in order to properly cache and serve your static resources.

Adding @angular/pwa schematic to your Angular application automatically registers manifest.json file to your static resource configuration on angular.json configuration. But if you’re using additional files on your root, like robots.txt, browserconfig.xml, or a custom icon set, you need to add those files to your build configuration.

This is the default asset configuration on your angular.json file after adding @angular/pwa schematic:

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

You may want to extend this configuration as you add static files to your root, or introduce an external plugin. Even more interesting in our case, you may want to introduce an additional service worker to your app on top of your automatically generated ngsw-worker.js.

This is an example asset configuration on angular.json from one of my PWAs:

"assets": [
  "src/manifest.json",
  "src/robots.txt",
  "src/browserconfig.xml",
  "src/favicon.ico",
  {
    "glob": "**/*",
    "input": "src/assets",
    "output": "assets"
  },
  {
    "glob": "**/*.svg",
    "input": "node_modules/@ionic/angular/dist/ionic/svg",
    "output": "./svg"
  },
  {
    "glob": "**/*-sw.js",
    "input": "src/app/sw",
    "output": "/"
  },
  {
    "glob": "**/idb-keyval-iife.min.js",
    "input": "node_modules/idb-keyval/dist/",
    "output": "/"
  }
]

7. Extending Angular service worker

As of February 2019, Angular service worker — aka ngsw doesn’t support the composition of another service worker. This means that you cannot extend Angular service worker’s default behaviour and add your flavour to it.

You can try and edit automatically generated ngsw-worker.js service worker file but every time you build your application for production, this file will be overridden by Angular, based on your configuration on ngsw-config.json.

This architecture may introduce a problem if you plan to do more than what Angular service worker offers to you. No worries though, there is a nice workaround to tackle this issue.

Introducing your own service worker file

You can introduce a new service worker file, say main-sw.js to your Angular app and import automatically generated ngsw within your new service worker.

Assuming you configured your sw files to be copied to your apps root folder — please refer to "**/*-sw.js" glob on the chapter “Configuring angular.json for static assets”, the following importScripts imports on your worker should resolve.

Create a new main-sw.js file in src/app/sw folder with the following content:

importScripts('ngsw-worker.js'); // automatically generated ngsw  
importScripts('messaging-sw.js'); // custom service worker #1  
importScripts('notifications-sw.js'); // custom service worker #2

After introducing your own service worker wrapper, you must change the service worker reference on your app.module.ts file.

ServiceWorkerModule.register('/main-sw.js', { enabled: environment.production })

Use Chrome DevTools’ Application tab to inspect your app’s service workers. A demonstration of extended service worker of the ITNEXT 2018 Conference PWA — https://itnext-summit-2018.firebaseapp.com

💡 TIP — By default, service workers are enabled for production environment. Angular recommends building for production and running http-server for testing service workers of your app.

8. Updating your PWA

A service worker is the backbone of a Progressive Web App. And, updating a PWA always starts at its service worker. Browsers regularly check attached service worker of a client app for a byte difference and once service worker file is updated, the browser automatically initializes an update process.

Source: https://deanhume.com/displaying-a-new-version-available-progressive-web-app/

8.1 App versions and update checks

In the context of an Angular service worker, a “version” is a collection of resources that represent a specific build of the Angular app. Whenever a new build of the app is deployed, the service worker treats that build as a new version of the app. This is true even if only a single file is updated. At any given time, the service worker may have multiple versions of the app in its cache and it may be serving them simultaneously.

Every time the user opens or refreshes the application, the Angular service worker checks for updates to the app by looking for updates to the ngsw.json manifest. This manifest file represents the “version” of an Angular build, along with all the files associated with ngsw-config file. If an update is found, it is downloaded and cached automatically, and will be served the next time the application is loaded.

— Angular docs

The ngsw.json manifest file, representing a build aka “version” of an Angular PWA:

{
  "configVersion": 1,
  "appData": {
    "version": "1.1.0",
    "changelog": "Added better resource caching"
  },
  "index": "/index.html",
  "assetGroups": [
    {
      "name": "shell",
      "installMode": "prefetch",
      "updateMode": "prefetch",
      "urls": [
        "/favicon.ico",
        "/index.html",
        "/main.cb67e635642476004207.js",
        "/polyfills.1840410d8aa59aab644c.js",
        "/runtime.a66f828dca56eeb90e02.js",
        "/styles.3ff695c00d717f2d2a11.css",
        "/vendor.3335969a60ee384a24da.js"
      ],
      "patterns": []
    },
    {
      "name": "assets",
      "installMode": "lazy",
      "updateMode": "prefetch",
      "urls": [
        "/assets/icons/icon-128x128.png",
        "/assets/icons/icon-144x144.png",
        "/assets/icons/icon-152x152.png",
        "/assets/icons/icon-192x192.png",
        "/assets/icons/icon-384x384.png",
        "/assets/icons/icon-512x512.png",
        "/assets/icons/icon-72x72.png",
        "/assets/icons/icon-96x96.png"
      ],
      "patterns": [
        "https:\\/\\/fonts\\.googleapis\\.com\\/.*"
      ]
    }
  ],
  "dataGroups": [
    {
      "name": "from-static",
      "patterns": [
        "\\/data\\/data\\.json"
      ],
      "strategy": "performance",
      "maxSize": 10,
      "maxAge": 86400000,
      "timeoutMs": 5000,
      "version": 1
    },
    {
      "name": "from-api",
      "patterns": [
        "\\/dashboard",
        "\\/user"
      ],
      "strategy": "freshness",
      "maxSize": 15,
      "maxAge": 3600000,
      "timeoutMs": 3000,
      "version": 2
    }
  ],
  "hashTable": {
    "/assets/icons/icon-128x128.png": "dae3b6ed49bdaf4327b92531d4b5b4a5d30c7532",
    "/assets/icons/icon-144x144.png": "b0bd89982e08f9bd2b642928f5391915b74799a7",
    "/assets/icons/icon-152x152.png": "7479a9477815dfd9668d60f8b3b2fba709b91310",
    "/assets/icons/icon-192x192.png": "1abd80d431a237a853ce38147d8c63752f10933b",
    "/assets/icons/icon-384x384.png": "329749cd6393768d3131ed6304c136b1ca05f2fd",
    "/assets/icons/icon-512x512.png": "559d9c4318b45a1f2b10596bbb4c960fe521dbcc",
    "/assets/icons/icon-72x72.png": "c457e56089a36952cd67156f9996bc4ce54a5ed9",
    "/assets/icons/icon-96x96.png": "3914125a4b445bf111c5627875fc190f560daa41",
    "/favicon.ico": "84161b857f5c547e3699ddfbffc6d8d737542e01",
    "/index.html": "40b6fc0e0fae9194170df9397b48487bcd139bcd",
    "/main.cb67e635642476004207.js": "622827b74fd2511ca3293cc9e7bc0873e40b38a0",
    "/polyfills.1840410d8aa59aab644c.js": "c59ac0163bbb63bf9a602a38fa41aaa3da1dae99",
    "/runtime.a66f828dca56eeb90e02.js": "078e320cc6fdaf355836c3b1c52b059cdd33fc7e",
    "/styles.3ff695c00d717f2d2a11.css": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
    "/vendor.3335969a60ee384a24da.js": "e06c17d4e5b96102d8bb7828bc473c1a4fce27ea"
  },
  "navigationUrls": [
    {
      "positive": true,
      "regex": "^\\/.*$"
    },
    {
      "positive": false,
      "regex": "^\\/(?:.+\\/)?[^/]*\\.[^/]*$"
    },
    {
      "positive": false,
      "regex": "^\\/(?:.+\\/)?[^/]*__[^/]*$"
    },
    {
      "positive": false,
      "regex": "^\\/(?:.+\\/)?[^/]*__[^/]*\\/.*$"
    }
  ]
}

Read more about ngsw app updates: https://angular.io/guide/service-worker-devops

8.2 AppData on ngsw-config.json

appData field in ngsw-config.json file enables you to pass any data (you want) that describes this particular version of the app. The [SwUpdate](https://angular.io/api/service-worker/SwUpdate) service includes that data in the update notifications. Many apps make use of this field to provide some additional info for the display of any popups, notifying users of the available update.

"index": "/index.html",  
"appData": {  
  "version": "1.1.0",  
  "changelog": "Added better resource caching"  
}

8.3 SwUpdate service

Angular handles its service worker updates via its own service called [SwUpdate](https://angular.io/api/service-worker/SwUpdate) from @angular/service-worker module. You can subscribe to UpdateAvailableEvent and UpdateActivatedEvent events on this service to be notified on service worker updates.

ITNEXT 2018 Conference PWA, app update demonstration — See source code on https://github.com/LINKIT-Group/itnext-summit-app

Following example demonstrates a prompt for users, which will be displayed when a new service worker version becomes available. By doing this, we provide an option for users to immediately apply the update.

import { SwUpdate } from '@angular/service-worker';
@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent implements OnInit {
ngOnInit() {
  if (this.swUpdate.isEnabled) {
    this.swUpdate.available.subscribe(async () => {
      const alert = await this.alertController.create({
        header: `App update!`,
        message: `Newer version of the app is available. It's a quick refresh away!`,
        buttons: [
          {
            text: 'Cancel',
            role: 'cancel',
            cssClass: 'secondary',
          }, {
            text: 'Refresh',
            handler: () => {
              window.location.reload();
            },
          },
        ],
      });

      await alert.present();
    });
  }
}

Please note that you don’t have to provide this manual update functionality. Service workers are automatically updated by the browser on the time of disconnection of all clients or pages attached to it. However, I recommend providing this immediate update option for the convenience of your users.

💡 TIP — Browsers automatically check byte differences of the attached main service worker file, which would be main-sw.js if you’ve extended ngsw. You should make sure that other sw files that you might import to your main service worker are not cached. This will be explained in detail on Firebase hosting configuration on next chapter.

9. Hosting your app on Firebase

Firebase is built around simplicity. It’s quite easy to set up a hosting and configure deployments for your application.

Once you’ve logged in to Firebase console, you can click on Add Project button and fill in the form below with your preference.

Creating a new project for your app on Firebase

The easiest way of using Firebase services is to make use of Firebase CLI through a console. To access Firebase CLI on your command line, run one of the following;

npm i -g firebase-tools
npx firebase // or use npx to avoid global installation

Setting up hosting on Firebase

After creating your project, navigate to Hosting tab under develop category. Click Finish in order to make your project available on CLI.

Initializing Firebase config

You can deploy your PWA to Firebase by simply executing 3 commands via Firebase CLI; login, init and deploy. We’ll only make use of hosting service of Firebase for now. In order to do that, you should execute firebase init on your project root and then check that with Space key and press Enter.

Options for initialising Firebase on your project

On the next step, it will show your existing projects to you to set up a hosting on. Select [create a new project] option to create a default project for your app. After that, answer the steps like below;

• What do you want to use as your public directory? dist/my-pwa — This is the path for your production build that is configured on angular.json file under outputPath.
• Configure as a single-page app (rewrite all urls to /index.html)? y
• File dist/my-pwa/index.html already exists. Overwrite? n

As an output of this setup, Firebase CLI creates 2 files in your project root: firebase.json and .firebaserc

10. Configuring a Firebase hosting for your PWA

It’s possible to configure your hosting on Firebase via firebase.json file in your project. You can see the default configuration of which Firebase CLI created for your project below;

{
  "hosting": {
    "public": "dist/my-pwa",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}

It’s important to be aware of a couple of points on this configuration.

• Since Angular is a SPA (Single Page Application), you must configure rewrite as above to point all sources to your index.html file.
• Do not deploy any file that keeps your credentials under no circumstances. Keys, secrets, and such confidential information on your configuration files that relies on the public folder you pointed out, might be exposed to the world immediately. Make sure to ignore any configuration file you have in your public folder, or else;

10.1 Adding custom HTTP headers for caching

Firebase hosting configuration allows you to add custom HTTP headers for your project.

This configuration is especially important for your PWA where you might want to cache your static assets and gzip them to improve your app’s loading performance. A long cache lifetime can speed up repeat visits to your page.

When a browser requests a resource, the server providing the resource can tell the browser how long it should temporarily store or cache the resource. For any subsequent request for that resource, the browser uses its local copy, rather than going to the network to get it. — Cache policy on Google Developers portal

Verifying cached responses in Chrome DevTools — Cache policy on Google Developers portal

Since Angular creates your static resources with a hash postfix in the filename, you can take advantage of introducing a long cache lifetime for those resources by adding Cache-Control HTTP header. When you do that, you should also consider invalidating your caches. However, invalidating caches of static resources is not required for your Angular app as Angular’s build system automatically changes the postfix hash in your resources’ file names when they’re updated.

Moreover, Firebase automatically compresses static resources with gzip and returns a response with Content-Encoding gzip header where it applies. But I’d like putting that explicit header anyway to make the intent visible.

Production build output of Angular where vendor chunk is enabled. Demonstrates hashes in filenames as well.

💡 TIP — Introduce vendor chunk to your production build configuration for your Angular app — see vendorChunk option in angular.json. This will help on your PWA’s cache strategy as you most likely will not update vendor libraries too often.

The following example demonstrates adding long cache lifetime and providing compressed static resources;

{
  "headers": [
  {
    "source": "**/*.@(js|css)",
    "headers": [
      {
        "key": "Cache-Control",
        "value": "max-age=31536000"
      },
      {
        "key": "Content-Encoding",
        "value": "gzip"
      }
    ]
  }
}

You might have noticed above that Firebase configuration accepts glob-like pattern for source files.

10.2 Keeping your additional service worker files fresh

If you make use of such cache configuration above for all your js and css files, you must create an exception rule for your additional service worker files. Here’s an example of no-cache exception;

{
  "headers": [
  {
    "source": "**/*-sw.js",
    "headers": [
      {
        "key": "Cache-Control",
        "value": "no-cache"
      }
    ]
  }
}

This rule will make sure that we’ll keep all our service worker files matching with the file name pattern \*/*-sw.js* fresh.

10.3 Adding HTTP/2 server push with link headers

HTTP/2 is currently enabled for all *.firebaseapp.com traffic and to utilize HTTP/2 on Firebase Hosting, you don’t have to do anything! It will automatically be served if the user’s browser supports it. Read more about it here:

However, you might want to manually introduce HTTP/2 server push to your app. By using Link headers, Firebase hosting introduced experimental support for HTTP/2 server push. Server push allows a server to automatically send the contents for additional resources when an initial request is made. A common use for server push is to send associated static resources — like JavaScript and CSS files when a page is loaded.

You need to add the Link header to your firebase.json config file with pointing out the path of your static resources in order to configure server push on Firebase hosting. Here’s an example;

{
  "headers": [
    {
      "source": "/",
      "headers": [{"key": "Link", "value": "</js/app.js>;rel=preload;as=script,</css/app.css>;rel=preload;as=style"}]
    },
    {
      "source": "/users/*",
      "headers": [{"key": "Link", "value": "</js/app.js>;rel=preload;as=script,</css/app.css>;rel=preload;as=style;nopush,</css/users.css>;rel=preload;as=style"}]
    }
  ]
}

10.4 A basic hosting configuration example

Following example demonstrates a configuration example of one of my PWAs. I recommend you to read the documentation of hosting configuration on Firebase for you to understand all possible configuration options.

Example of a full firebase.json configuration file that I use on one of my PWAs:

{
  "hosting": {
    "public": "www",
    "ignore": [
      "firebase.json",
      "3rdpartylicenses.txt",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ],
    "headers": [
      {
        "source" : "**/*.@(jpg|jpeg|gif|png|svg)",
        "headers" : [
          {
            "key" : "Cache-Control",
            "value" : "max-age=86400"
          },
          {
            "key": "Content-Encoding",
            "value": "gzip"
          }
        ]
      },
      {
        "source" : "**/*.@(js|css)",
        "headers" : [
          {
            "key" : "Cache-Control",
            "value" : "max-age=31536000"
          },
          {
            "key": "Content-Encoding",
            "value": "gzip"
          }
        ]
      },
      {
        "source": "**/*-sw.js",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "no-cache"
          }
        ]
      }
    ]
  }
}

11. Deploying your PWA to Firebase

Deploying an app to Firebase is simple as it can be. Just execute firebase deploy via Firebase CLI in your project root and you’re good to go!

You might need to add a project if you haven’t done already

12. Auditing your PWA with Lighthouse

Lighthouse is an open-source, automated tool for improving the quality of web pages. You can run it against any web page, public or requiring authentication. It has audits for performance, accessibility, progressive web apps, and more.

Auditing a PWA can be done on online audit runner, on Chrome DevTools and through Lighthouse CLI.

12.1 Using online audit runner

You can run Lighthouse audits by navigating to the link below and entering a URL of which application you’d like to run the audits on.

12.2 Using Chrome DevTools

Once you configure your PWA by following the tips on this article and deploy your app to firebase with recommended configuration, your app is ready for an audit. You can run an audit on Chrome DevTools and see a score of 100 for the Progressive Web App audit.

💯score on Lighthouse PWA audit — Chrome DevTools Audit

12.3 Using Lighthouse CLI

An audit with Lighthouse can be automated on your continuous integration environment via Lighthouse CLI. This will make sure that not any of your changes will impact the score on any of the audits you set — see CLI options within your Lighthouse regression.

💡 TIP — You can compare the Lighthouse reports of your current and previous audits to make sure there’s no impact to your app related to your changes.

The following command will execute a headless Chrome and run audits against the url and then will display a report.

npx lighthouse https://my-fancy-pwa.firebaseapp.com --chrome-flags="--headless" --view

Lighthouse CLI report, viewed as html

💡 TIP — Executing nightly regressions on your production app to monitor it against updated PWA audits will help you to align with future PWA best practices as the list of audits get updated in time.

What else is there for your PWA?

With the ever-growing power of the web, anything you can introduce to a web app is an option for your PWA. Make sure to check out WebKit Feature Status for iOS and Chrome Platform Status for Android platform compatibility for the features and Web APIs you’d like to adapt.

One year after the first beta of iOS 11.3, Apple recently released the first beta of iOS 12.2. This is the first version since PWA support was introduced and there are quite good improvements in it — focusing biggest issues of PWAs on iOS. Read more about it here:

Furthermore, you can get inspired by the capabilities of your browser by simply browsing https://whatwebcando.today and https://tomayac.github.io/pwa-feature-detector/ on your mobile or desktop browser.

If you’d like to add push notifications functionality to your PWA, you can follow the guide below of my colleague Ural.

Follow me on Twitter for more tips like the ones in this post.

Please don’t forget to like and follow if you find this article useful. And, feel free to write comments about your PWA development journey. I’d love to hear all about it!

@ngrx provides a set of clean, well-tested libraries for reactive programming in Angular applications. — http://ngrx.github.io/

I’ve been using NgRx for building fairly complex applications for one of our enterprise clients since last year.

My journey through NgRx includes building a brand new application with the latest version of NgRx, migrating a stateful Angular application to a reactive one, and also migrating an old NgRx application to the latest version.

I’d like to share my experiences with it so far, by giving some tips and tricks to both existing users and complete beginners of NgRx.

The examples in this article are based on NgRx v6 which uses classes for actions, rather than creators. To see updated version — v8 examples of the best practices on this blog post, you can watch my talk at angularday conference in Verona from May 2019:

Use schematics

If you’re not familiar with what schematics is in Angular world, please take a look at this post first.

NgRx team has introduced @ngrx/schematics with version 5. If you’d like to reduce the boilerplate, you’ll definitely love this. It will also help you to align with non-officially existing style guide.

NgRx team loves complaints on boilerplate. Brandon don’t block me, bro. Seriously.

A good trick on NgRx schematics is to set it as default collection for your Angular application. After installing @ngrx/schematics, execute following to set it as default collection for your Angular application.

ng config cli.defaultCollection @ngrx/schematics

With 3 simple CLI commands, you can generate a boilerplate code for the basis of your new reactive feature, including TestBed configurations. It’s structured exactly as it’s in NgRx example-app.

ng g module user --flat false  
ng g feature user/store/user --module ./user/user.module.ts --group  
ng g container user/containers/UsersPage

It’s a pretty big deal actually!

Same folder structure as it’s in the example-app — https://github.com/ngrx/platform/tree/master/projects/example-app

You can take a look at the documentation for further usage instructions — https://github.com/ngrx/platform/tree/master/docs/schematics.

Maintain a good action hygiene

Actions are the foundation of an NgRx app. It’s so important that a good action hygiene can help both business development and software engineers at the same time.

Good actions are actions you can read after a year and tell where they are being dispatched. — Mike Ryan

As Mike Ryan states on his Good Action Hygiene with NgRx talk, poor processes lead to poor quality applications. I’d like to stress the common pitfalls from his talk as a reference, hoping that it will help more people avoid them.

Don’t reuse actions

Actions should capture events, not commands.

Try to model your actions as unique events on your system so that you can easily understand where it comes from a year later.

Reducers and effects should be the decision makers

Separate the description of an event and the way it’s handled in your app. Leave the decision making to your reducers and effects, your components should not decide how state changes.

Avoid using generic action types

When you take a look at your code or your store devtools logs, it should be clear for everyone how your application behaves and what’s the origin of an event.

Especially for the development team, pinpointing any of the actions in a big application helps everyone more than you can imagine.

A good formula to accomplish this is using [Source] Event format.

Generic actions vs exclusive actions — An example from Mike’s presentation

Don’t do action subtyping

This pitfall is strongly related to action reusing. Chances are, you won’t fall into this if you avoid the first pitfall. Don’t push it to build generic actions with sub types and be as unique as possible with your actions.

Nested conditional in a reducer — An example from Mike’s presentation

Falling into this pitfall may bring conditional branches all throughout your application. It will be a pain in the neck to maintain them when they add up by your application scales up. Avoid nested conditionals in reducers and effects!

Simplify your reducers with @ngrx/entity

NgRx team works hard on reducing the boilerplate. That’s one of the reasons of building such a library. But there are more!

You possibly deal with collections in your store, and maintaining your store data with large and complex collections of entities might give you a headache, not to mention the boilerplate code it brings to your reducers.

@ngrx/entity is there for the rescue to simplify your reducers and domain models.

Entity State

After setting up your entity adapter, your entity state will look like the following in your store.

interface EntityState<T> {  
  ids: string\[\];  
  entities: { \[id: string\]: T };  
}

There are a couple of reasons for maintaining a dictionary of entities and a list of ids in your entity state:

1. In order to keep your collection sorted along with having a dictionary, you need an ordered list. That’s why ids array is part of the entity state.
2. Lookup actions are expensive operations most of the times if you maintain your data as a list. Using a dictionary for your entities is much faster compared to searching through an array.

CUD operations (Create, Update, Delete)

Entity adapter brings many useful methods for your CUD needs in the store.

Take a look at the following in-app events example of mine, to see available operations, as well as different use cases with partial changes object.

import * as fromEvents from '../actions/events.action';
import { createEntityAdapter, EntityAdapter, EntityState } from '@ngrx/entity';
import { Event } from '../../models/event.model';

export interface EventsState extends EntityState<EventEntity> {
  loaded: boolean;
  loading: boolean;
  error: Error;
}

export function sortDescByUpdatedDateTime(a: EventEntity, b: EventEntity) {
  return b.data.updatedDateTime - a.data.updatedDateTime;
}

// Note that you can build your custom sort function as above and pass it down
// to your entity adapter to automatically sort ids array based on your sort logic
export const eventEntityAdapter: EntityAdapter<EventEntity> = createEntityAdapter<EventEntity>({
  selectId: (event: EventEntity) => event.data.eventId,
  sortComparer: sortDescByUpdatedDateTime,
});

export const initialState: EventsState = eventEntityAdapter.getInitialState({
  loaded: false,
  loading: false,
  error: null,
});

export interface EventEntity {
  data: Event;
  read: boolean;
}

export function eventsReducer(state = initialState, action: fromEvents.EventsActionsUnion): EventsState {
  switch (action.type) {
    case fromEvents.EventsActionTypes.LoadAllEvents: {
      return {
        ...state,
        error: null,
        loading: true,
      };
    }

    // You can use one of the ...many operations here, based on your business requirements
    // addMany, updateMany and upsertMany are available
    case fromEvents.EventsActionTypes.LoadAllEventsSuccess: {
      return eventEntityAdapter.upsertMany(action.payload, {
        ...state,
        loading: false,
        loaded: true,
      });
    }

    case fromEvents.EventsActionTypes.LoadAllEventsFail: {
      return {
        ...state,
        loading: false,
        error: action.payload,
      };
    }

    case fromEvents.EventsActionTypes.ClearOldEvents: {
      const idsOfexpiredEntities = /* your logic here */;
      return eventEntityAdapter.removeMany(idsOfexpiredEntities, state);
    }

    // Changes object is an object with Partial<T> type of your entity interface
    // You can consider it as an object which will be deep merged to your entity
    case fromEvents.EventsActionTypes.ReadEvent: {
      return eventEntityAdapter.updateOne(
        {
          id: action.eventId,
          changes: {
            read: true,
          },
        },
        state,
      );
    }

    // Note that you need to provide an array of Update<T> to the updateMany operation
    // UpdateStr<T> = {
    //   id: string;
    //   changes: Partial<T>;
    // };
    case fromEvents.EventsActionTypes.ReadAllEvents: {
      return eventEntityAdapter.updateMany(
        [...state.ids].map((eventId: string) => ({
          id: eventId,
          changes: {
            read: true,
          },
        })),
        state,
      );
    }
  }
  return state;
}

export const getEventsLoading = (state: EventsState) => state.loading;
export const getEventsLoaded = (state: EventsState) => state.loaded;
export const getEventsError = (state: EventsState) => state.error;

Entity adapter and some of the CUD operations — reducer

Default Selectors

Your entity adapter instance exports 4 useful selectors for you. You can export them in your selectors file, along with your custom ones if needed.

export const {  
  selectIds,  
  selectEntities,  
  selectAll,  
  selectTotal,  
} = yourEntityAdapter.getSelectors();

Use ngrx-data if you’ve too many domain models

If you want to take reducing the boilerplate code of your domain models to another level, you might want to take a look at ngrx-data library. It’s not part of official @ngrx/platform just yet, but they announced that it will be soon.

It’s not an alternative for ngrx, but instead it’s an additional flavour for it to extend managing domain models. As it’s stated on their documentation:

Many applications have substantial domain models with 10s or 100s of entity types such as Customer, Order, LineItem, Product, and User.

In plain ngrx, to create, retrieve, update, and delete (CRUD) data for every entity type is an overwhelming task. You’re writing actions, action-creators, reducers, effects, dispatchers, and selectors as well as the HTTP GET, PUT, POST, and DELETE methods for each entity type.

In even a small model, this is a ton of repetitive code to create, maintain, and test.

The ngrx-data library is one way to stay on the ngrx path while radically reducing the “boilerplate” necessary to manage entities with ngrx.

If you haven’t used @ngrx/entity in your NgRx application yet, I strongly advise you to do so. You can read more about it on the following introduction post - Introducing @ngrx/entity.

Use selectors, seriously

A selector is a pure function that slices a part of your state. They’re small query functions that filter out your state object. Other than utilizing selectors inside your view layer, it is additionally conceivable to compose selector functions on other selectors.

You should start using selectors for both compliance with DRY principle and performance concerns. Pure selector functions will help you avoid slicing through the state, every time you need a piece of it, eventually saving you from repeating yourself. For the performance benefits it brings, let’s have a look at the following quote from NgRx selector docs:

Because selectors are pure functions, the last result can be returned when the arguments match without reinvoking your selector function. This can provide performance benefits, particularly with selectors that perform expensive computation. This practice is known as memoization.

— NgRx selector docs

Here’s an example usage of selectors, including composing selectors from different features:

Composing selectors — selector

Take a look at official docs for advanced use cases of selectors, it will definitely help you to solve complex problems in your app: https://github.com/ngrx/platform/blob/master/docs/store/selectors.md

Keep your store clean

A common debate on NgRx store is about which state actually belongs to the store. When I watched Mike Ryan and Brandon’s Reducing the Boilerplate with NgRx talk on youtube, it immediately took place in my head. I was already thinking through this question and evaluating my application’s state without a structure in place which they introduced clearly during the talk.

The structure that they pitched definitely helps on deciding which state belongs to the store or not.

The answer is SHARI! If your state fits in any of the categories below, you should keep it in your store.

Shared
 — Shared state is accessed by many components and services

Hydrated
 — State that is persisted and hydrated from storage

Available
 — State that needs to be available when re-entering routes

Retrieved
 — State that needs to be retrieved with a side effect

Impacted
 — State that is impacted by actions from other sources

Serialization and hydration

If you’re like me, you probably prefer to persist data for part of your application store — like app settings, in user’s browser storage and hydrate it. This can be done through meta reducers.

Serialization

Just be careful about serialization when you put a data in your store. Your data must be serializable, which means you cannot put your Map() or Set() object instances in the store.

An easy way of checking whether your object is serializable or not is, simply comparing your original object with the output of the following:

JSON.parse(JSON.stringify(obj))

Persistent storage and hydration

I use ngrx-store-localstorage package to persist store data in localStorage. Here’s an example of how it’s done, using a meta reducer:

Persistent storage of your store — reducer

Persistent storage of your store — feature module

By the way, NgRx team has announced that there will be a built-in support for hydration and serialization with the next version — 7. So, looking forward to it!

Follow me on Twitter for more tips like the ones in this post.

Please don’t forget to like and follow if you find this article useful. May the purity be with your functions and components!

I want to share my experience and hopefully inspire anyone those who are in the process of setting up or maintaining CI/CD. Although it’s a fairly technical article, I’ll also touch business values for luring business owners and managers. So, please bear with me.

Why should you start using continuous delivery pipeline?

You may have too many manual processes and a possible bottleneck on your software deliveries. On daily basis, it can decrease your efficiency on delivering features because of the time you lose and the effort you make on context switching, manual building, fixing the builds and dependency issues, dealing with iOS code signing issues, manual archiving, manual deployment, manual re-packaging, code re-signing, and so on and so forth.

By introducing CI/CD pipeline into your organisation, you can improve the quality of your hybrid mobile apps, accelerate deliveries and automate your processes.

Before going forward, I’d like to go over Continuous Integration, Continuous Delivery, and Continuous Deployment terms. I think it’s important to clarify what they are and how they’re connected. In fact, I’d like to stress what it actually means for your business.

Continuous Integration (CI)

Continuous integration — the practice of frequently integrating one’s new or changed code with the existing code repository — should occur frequently enough that no intervening window remains between commit and build, and such that no errors can arise without developers noticing them and correcting them immediately.

What it could mean for your app and your team

• Assuring code quality by testing unit functions
• Preventing compilation errors
• Code linting
• Early detection of possible issues with external dependencies, such as npm packages and plugins
• Increasing your code coverage
• Faster build times in time
• Guarding a stable, working development version
• Transparency with displaying the results of the builds to everyone
• Deployment automation

Continuous Delivery / Deployment (CD)

Continuous delivery is an extension of continuous integration to make sure that you can release new changes to your customers quickly in a sustainable way. This means that on top of having automated your testing, you also have automated your release process and you can deploy your application at any point of time by clicking on a button.

Continuous deployment is the next step of continuous delivery: Every change that passes the automated tests is deployed to production automatically. Continuous deployment should be the goal of most companies that are not constrained by regulatory or other requirements.

What it could mean for your iOS app and your team

• No more xcode codesigning issues on development and distribution certificates anymore since you don’t need to build on our local computers
• No more context switching for developers to be able to provide a QA build for testers, users, and stakeholders
• No more build errors due to mismatch between system tools and dependencies
• No more waiting times for testers to have a specific build/revision installed on a device
• No more manual release preparation for production with re-building, re-packaging and re-signing with production enterprise certificates
• No more necessity for our customers and stakeholders to stop by the office in order to get a build/version — thanks to beta app distribution
• Any developer or tester is able to trigger a build remotely out of a branch/revision and deploy it for QA or PROD (if you follow continuous delivery approach)
• Any developer or tester is able to trigger a build remotely out of pushing a new code or merging a PR and deploy it for QA or PROD (if you follow continuous deployment approach)

From now on, I’d like to focus on tips and tricks on setting up a CI/CD for your hybrid applications. To avoid complexity, I just refer to ionic app on iOS platform in my examples.

Find bottlenecks and automate manual processes

One of the blockers you might have for setting up your CI environment might be something you have to automate. It can be codesign operation, resign operation, repackaging or a web page that you need to upload a file or submit a form.

Analyse

Start with analysing your manual processes on your delivery pipeline. Is it a change request you have to submit? Is it a distribution for QA? Is it a resigning operation? Define them and think about the ways to automate them.

Automate with fastlane

Integrate fastlane! Fastlane is a great platform which focuses on solving the problems that existed for years in mobile development environment.

“fastlane handles tedious tasks so you don’t have to” — fastlane.tools

It helps you to organise and maintain your provisioning profiles and certificates for the codesigning, integrates beta deployment and so on.

Automate with your own scripts

For the processes that you can not automate through fastlane or any other helpful platform or library, you may need to write your own scripts.

Always browse npmjs.com before writing your own node.js script

You may require to repackage your application, resign it, upload it to a web page or an enterprise MDM provider. In that case, you should create your own bash executables in order to automate those of your daily operations. Browsing npm packages and building your scripts with node.js might be wise since it’s a large community and there could already be a package for your needs.

“Puppeteer is a Node library which provides a high-level API to control headless Chrome or Chromium over the DevTools Protocol. It can also be configured to use full (non-headless) Chrome or Chromium.”

Puppeteer is a very powerful library and a great toolset if you need to deal with web pages for some of your manual processes. It can be your best friend for automating browser based processes.

I used puppeteer to automate a resigning operation where I had to upload my repackaged application build to a web form and download a resigned one from Nexus servers.

Set up CI configuration

Compiling and building an application package for iOS platform requires an iOS device, xcode, and code signing as we all know. No matter which CI solution you use, you need to identify and point the CI to the right agents for your build configuration.

Make sure that you have build agents with right capabilities for your automated processes

Prerequisites for your build agents

Define your requirements and set prerequisites and capabilities for your CI agent. For instance, let’s say you’re building an ionic app and you have automated some tasks with fastlane and puppeteer. You may need brew, nvm, cordova, xcode, yarn, ionic, ios-deploy, fastlane and google-chrome installed for your agents.

You need to make sure those tools are installed on you CI agent. And as the first step on your build configuration, it’s wise to check if those tools are installed on CI system and if not, just install them with command line scripts!

Assert and install the tools you require for your scripts

Manage developer and enterprise distribution certificates and codesigning on CI agent

If you’re building mobile apps for iOS, you might already know that codesigning is a challenging task. It’s hard to understand and even harder to maintain if you’re working in a large organisation with multiple product teams.

I recommend you to use fastlane match to manage your development certificates for your teams. You should also use match to install your distribution certificates on your CI agent.

You need to introduce a new step in your build configuration to download provisioning profiles and certificates from your certificate repository if you’re using match. Otherwise, you can use sigh & cert to download it right from your Apple developer account. Following code snippet is an example of how you can handle iOS code signing on macOS build agent.

Download your provisioning profiles and certificates, set them to your custom keychain on the CI

I’d like to point to an important detail here. In order to have xcode get your certificates from the keychain during the build, your keychain should be unlocked — see line 7 on the above snippet. Otherwise, your build will be hanging on unlock keychain prompt.

Maintaining your CI scripts

Although you can add command line scripts to your build configuration of your CI, I would advise keeping your build scripts on your source control system. It will be easier to develop, review and maintain your scripts and it will make it possible to see the revision history.

Folder structure example for maintaining your CI scripts

Setting up steps on your build configuration

After building your custom scripts, you need to assign them to your build configuration of steps. Here’s an example of build steps for creating app artifact which is built on Bamboo.

Once you have your artifact (IPA file in our case), you may want to use it for beta deployment. To accomplish that, you can introduce a new stage for deployment and setup your build configuration similar to the one above to deploy the artifact you just built.

Beta app distribution for continuous deployment

Beta app distribution is a very nice way to distribute your app to QA, key users and stakeholders before publishing them to production users. Apple introduces TestFlight for commercial apps which is unfortunately not available for enterprise developer accounts.

However, there are other great options for enterprises which serve the same objective. See HockeyApp, Fabric Beta and TestFairy for third party beta distribution services.

If you’re using fastlane, you can get advantage of using prebuilt scripts per beta service — see fastlane beta. It has built-in actions for TestFlight, Fabric Beta, HockeyApp and TestFairy. Otherwise, you can also easily communicate with their APIs to upload your package and distribute it.

Distribution flow of beta app builds

You can setup an automated distribution stage on your CI as an additional step on your builds or use deployment pipeline of your CI.

Down below, you see a simple bash script which uploads your app artifacts to HockeyApp. HockeyApp automatically distributes this deployment to selected user group and sends email/slack notifications accordingly with your app’s installation link in it.

In case of you don’t use fastlane, it’s not that complicated to write your own beta app deployment script

In a nutshell

Although this is a longer article than I planned, it’s still an overview of the whole pipeline with some in-depth topics such as code signing, CI configuration and automating processes.

I hope it helps you to automate your processes and enable CI/CD for your organisation if it’s not there yet. Otherwise, you might feel the emotional cycle of manual delivery.

We all fell down the cliff of urgency. I feel you.

Please leave comments if you have any questions or remarks! I’d be glad to hear your experience on your journey. Don’t forget to like and follow if you find my article valuable. Cheers!