How to add a Web App Manifest and mobile-proof your site

Published in

Dev Channel

4 min readFeb 17, 2017

It’s the year 201x, and everyone has a phone — statistically an Android phone, if it’s a smartphone. Most importantly, it’s the primary and only internet device for the average person. 📳⚠️

∴ your site deserves to work well on mobile.

This article just covers the technical steps 🛠️ for making your site work well on mobile these days. Let’s go!

0. Specify a viewport meta tag

If your site has literally never been mobile-optimized, chances are that opening it will give you a horrible experience involving panning and zooming. Add a meta tag. Go, now, look it up somewhere else.

1. Add a Web App Manifest to your site

This is a JSON file ⚙️ which describes how your site is turned into an “application” on a user’s home screen or in their application list.

website with Web App Manifest (BIGGEN) vs without (Matcher), a boring default

In 2016, about 10% of all eligible sessions (Android users) of Santa Tracker 🎅🎄 began via the home screen icon. So it’s worth doing.

basic manifest.json

Copy some existing JSON and modify it, e.g., the code just above.
Give your site a name and a short name (used under the icon).
Specify icons, including one of at least 256x256 pixels.
(optional) Set a background_color and theme_color that show while your site is loading.
Finally, save the file and add it to your page’s<head> —
<link rel="manifest" href="manifest.json" />

the preview shown before your site is ready

That’s it. You’re done. You can even validate your site with an online tool, but mostly you should celebrate with a donut. 🍩

2. Set a theme color

In Chrome for Android and a small list of other browsers, your website can configure the toolbar color. If you leave this out, it will be default black.

This is even simpler than it looks. Android will actually dim 🔅 the color you give it: so you can literally specify the primary background color of your site, and even if that abuts 🍑 the toolbar, the color will look different.

Specify it inside <head>— <meta name="theme-color" content="red" />
If you’re feeling motivated, you can even change this at runtime — maybe to get your user’s attention with a visual aid 🚨

3. Traditional icons

Your site might already have a favicon — the cute icon you see next to a tab’s title, or as part of a bookmark — since there’s nothing specifically mobile about it.

However, here’s a refresher with two options —

a. Write them manually

You can describe a number of icons inside <head>, like this —

<link rel="icon" href="icon-256.png" sizes="256x256" />
<link rel="icon" href="icon-128.png" sizes="128x128" />
<link rel="icon" href="icon-64.png" sizes="64x64" />

This is fine, but just a pain 😩. You can probably get away with just specifying a couple of small ones — 128x128 and lower — since they’re just for that tab icon. Your user’s browsers will pick the best size.

It can also be good to include a hand-crafted 16x16 and 32x32 icon for older browsers on low-DPI screens. You can express a lot more in crisp pixel art than you can by just resizing a high-quality, alpha, gradient 256x256 icon at a tiny size.

b. Use a helper library

Google has released a drop-in library called pwacompat that will actively read your site’s Web App Manifest and generate the required icons. You should still follow the above advice — include a variety of icons, including small, crisp options — but you can just specify them in your manifest.

It’s simple. Just drop this script tag in after your manifest —

<link rel="manifest" href="manifest.webmanifest" />
<script
  async
  src="https://unpkg.com/pwacompat"
  crossorigin="anonymous"></script>

pwacompat turns your manifest into sensible HTML tags

I am biased — I’m the primary author of this helper. However, I use this on every site I build, as I can forget everything to do with icons and just drop in one script tag. Done! 🎉

What are my next steps?

You’ve added a Web App Manifest, so if users install your app to their home screen, they get a great experience. But you can also leverage this to actually prompt users to do this automagically!

Service Worker + manifest resulting in a prompt

If you serve on HTTPS, and have a manifest plus a Service Worker, browsers will show this prompt after some magic level of engagement is detected.

What’s a Service Worker? It’s complicated. It helps you cache your website offline. But- we’re going to ignore all of that. Inside a script tag, add —

This registers a Service Worker, which can just contain the single line—

self.addEventListener('fetch', (event) => {});

Congrats! You’ve entered the modern, mobile-friendly web world. (If you’d like to build a Service Worker that actually caches your website offline, be sure to check out Google’s introduction).