Getting started with Progressive Web Apps (part 2)

Getting started with Progressive Web Apps (part 2)

In part 2 of learning how to create Progressive Web Apps, we'll take a look at the new app manifest that you can use to tell the browser the name of your app, where to find the app icons and install your app to the home screen (on both desktop and mobile).

When the user first visits your Progressive Web app, it looks just like a regular website.

On subsequent visits to your site, roughly the third or the fourth visit, the browser will display a prompt asking if the user would like to install the app to their home screen, but only if you've configured it to do so. There's two parts to this, and one of them is attaching a manifest to your index.html. 

This blog article will detail everything you can add to this manifest.

Creating a manifest

When the user launches the app from the launcher or the home screen, the app blends into the user`s environment. The app is top-level, full-screen and works offline. How much offline functionality it offers is of course up to you. One important thing to remember is that if you decide to go with a standalone configuration, you will have to remember to facilitate navigation because the user will not have access to the browser’s back button.

There are two main technologies involved in making this happen: the app manifest and the service worker.

The service worker is a code written in JavaScript that is executed in the background by the browser and is independent of the regular app code that you write that deals with the DOM. In fact, the service worker cannot touch the DOM at all. What is it good for then, you may wonder? The main selling point of a service worker is that it can intercept network requests, which is how it can serve cached content and can act on network request before they are made.

Caching strategies can be quite complex. In fact, there’s an old saying in computer science that goes like this:

There are only two hard things in Computer Science: cache invalidation and naming things. 
- Phil Karlton

There are also variations on this that include concurrency bugs, garbage collection, and off-by-one errors. Caching is especially hard, and we do not have to look further than the now deprecated Application Cache technology that was introduced in 2010. With Application Cache, it was very easy to cache some files. The problem was that you could never be sure the cache was ever invalidated.

The other technology that makes Progressive Web Apps work is the Web app manifest. This manifest is the means you use to tell the browser that it is dealing with a Progressive Web App. The manifest is a JSON object that lets us define settings such as the the name and description of the app, the app icon, the default orientation of the application, the app’s homepage, the app’s theme and background colors and the scope of the app. The last part is important because it lets you tell the browser what pages belongs to the Progressive Web App, and which ones does not.

Adding the manifest to your index.html

Let’s take a look at how the manifest is structured. It usually lives in the root of your application, alongside index.html and while it is not strictly required, it makes sense to call it manifest.json. In your index.html you reference it with this snippet within your <header> section:

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

And here’s how the content of a typical manifest.json looks like when you bring it up in Chrome Developer Tools and display the members. They are grouped and presented so that you’ll get a quick overview of how they will appear in the browser, on the start screen and so on. 

Let’s look at all the current accepted key/values that you can define.

App manifest members

Some of the member properties may seem self-explanatory, but there are facets to each that requires some understanding, so it is worthwhile to examine each member in detail.

First, note that the order is unimportant, but it is common to start with the descriptor values, the instructions, the images and then any related values.


Provides a human-readable name for the app.

"name": "My first Progressive Web App"


Provides a human-readable short name for the app. This is displayed when there’s no space to display the full length name of the app, and should be 12 characters or less.

 "short_name": "My PWA"


Provides a human-readable description of what the app does.

"description": "My first Progressive Web App is a very simple starter app"


Defines the URL that loads when user launches the application from the home screen or from the operating system’s task switcher.

"start_url": "./?utm_source=web_app_manifest"


Defines the navigation scope of the application. The manifest only when the user views a page within the scope. Outside the scope the manifest will not apply and the browser will display the page as a regular website.

"scope": "./"


Defines the primary text direction for the name, short_name, and description members. Combined with the lang member, it can assist in correct display of right-to-left languages (rtl). Default is left-to-right (ltr).

"dir": "ltr"


Defines the language for the name, short_name, and description members.

"lang": "en"


Defines the preferred display mode for the app. Optional values are: standalone, fullscreen, minimal-ui and browser.

"display": "standalone"


Defines the default orientation for the app. Optional values are: any, natural, landscape, landscape-primary, landscape-secondary, portrait, portrait-primary and portrait-secondary.

"orientation": "portrait"


Defines the expected background color of app. This may be used by the browser to draw a background color for the app when manifest is available, but before the stylesheet is loaded. The idea is to provide a smooth transition between launching the app and presenting it after the shell is loaded.

"background_color": "blue"


Defines the default theme color of app. This is a hint to to the browser that if possible, it should use the given color when presenting the app rather than defaulting to the browser default. This value should be matched to a header value in your html-file (<meta name="theme-color" content="#2E3AA1">)

"theme_color": "red"


Provides a list of icons that can serve as application icons in various contexts. Each object can contain the following values: src (the image path), sizes (a string containing the image dimensions it is valid for, separated by spaces) and type (the media type of the image/images).

"icons": [{

        "src": "images/icon-128x128.png",

        "sizes": "128x128",

        "type": "image/png"



Provides a list of native applications that are accessible to the underlying platform. These are meant to serve as an alternative native version of the web app.

"related_applications": [{

   "platform": "play",

   "url": "",

   "id": "com.example.mypwa"

  }, {

    "platform": "itunes",

    "url": ""



A Boolean value that hints whether the given related_application is preferred over the web application. Defaults to false.

 "prefer_related_applications": false

Here's an example of a manifest populated with the most common fields:

In the next part of this article series, we'll examine the role of web and service workers.


Om bloggeren:
Frontendutvikler med sans for JavaScript. Glad i å snakke om programmering, og har utgitt boken ReactJS Blueprints på Packt forlag.

comments powered by Disqus