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

Sam Thorogood
Dev Channel
Published in
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
  1. Copy some existing JSON and modify it, e.g., the code just above.
  2. Give your site a name and a short name (used under the icon).
  3. Specify icons, including one of at least 256x256 pixels.
  4. (optional) Set a background_color and theme_color that show while your site is loading.
  5. 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.

theme color #512da8

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" />
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).



Sam Thorogood
Dev Channel

Don’t use Medium.