Nitya Narasimhan, Ph.DWelcome to Day 3 of #30DaysOfPWA! New to the series? Three things you can do to catch up:
- Read the kickoff post below for context.
- Watch the GitHub Repository for updates.
- Bookmark #30DaysOfPWA Blog for resources.
This is a shortened version of this canonical post for the #30DaysOfPWA.
What We'll Cover Today
- What is a Web App Manifest?
- What should a minimal Manifest provide?
- How do manifest properties drive PWA capabilities?
- How can I create and validate my Manifest?
- Exercise: Inspect the manifest.json for sample PWA
Let's Recap The Week So Far:
Day 1: We learned PWAs are web apps that are progressively enhanced to deliver experiences that scale to device and platform capabilities. They can behave like native apps on richer platforms and fall back to regular website behavior on less capable ones.
Day 2: We learned PWAs are enabled by open web technologies like Service Workers, Web App Manifest & HTTPS, and by support for modern Web APIs. They power desirable PWA characteristics like installability and network independence in a cross-browser compatible way.
Plus, we picked a Sample PWA to look at as we explore the concepts.
Today, we look at Web App Manifest and understand how it enables PWA installability and discoverability.
What is a Web App Manifest?
Installability is a desirable characterstic that allows PWA to be added to a device home screen and behave like other native apps - e.g., users can launch them, pin them to Taskbar, find them through device search etc.
The Web App Manifest is an open web specification of a JSON format that is critical to making PWAs installable. Functionally, it governs how your PWA looks and behaves when installed on device by defining the properties (key-value pairs) that characterize its appearance and behaviors. In other words, it describes details about your web app, such as your app name, description, icons, and more.
A Sample PWA Manifest
Let's take a look at what a real manifest looks like using a Sample PWA. I'm using DevTool Tips - and I can view its manifest in two ways:
- From runtime. In yesterday's post we learned to inspect the app with browser DevTools to find the Manifest section under the Application tab.
-
From source. Look for a manifest.json file. Apps may choose to use a
app_name.webmanifestnaming convention if they serve it with anapplication/manifest+jsonMIME type. You can find a<link rel="manifest" href="manifest.json">inside the<head>tag of the page. Thehrefwill specify the file name of the manifest file.
Here's what my sample PWA's manifest.json looks like.
{
"name": "DevTools Tips",
"short_name": "DevTools Tips",
"start_url": "/",
"categories": [
"productivity",
"devtools",
"browser",
"education"
],
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#ffffff",
"scope": "/",
"description": "A collection of useful cross-browser DevTools tips",
"icons": [
{
"src": "/assets/logo-192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/assets/logo-512.png",
"sizes": "512x512",
"type": "image/png"
}
],
"screenshots": [
{
"src": "/assets/screenshot-home.png",
"sizes": "1992x1773",
"type": "image/png"
},
{
"src": "/assets/screenshot-tip.png",
"sizes": "1992x1773",
"type": "image/png"
}
],
"url_handlers": [
{
"origin": "https://devtoolstips.org"
}
]
}
Manifests are like App Resumes
That's a lot to take in right? It helps if you can put these properties into a few buckets - here's what I see:
- Identity - e.g., name, categories, starting URL.
- Characteristics - e.g, icons, colors, screenshots.
- Capabilities e.g., url_handlers
Wait - doesn't this remind you of a resume? The identity information, the profile headshots, the list of skills? That's exactly how I think of it:
- A Web App Manifest is like a resume for the application.
- The browser is where the application currently "works".
- Installability is the "interview" to work in a new place (on device).
- Discoverability is helped by "publishing" app resumes (to app stores).
The visual explains how this analogy works for PWA.
The browser is like an amazing workplace where people look out for your success. PWAs are apps "working" there - they keep an updated "resume" (manifest) and "link" it in their HTML to tell the browser they can work "remotely" (on device). The browser uses it to "advertise" this to users ("Install This Site As An App"). Make sense?
If the user clicks that Install prompt, it triggers an "interview" between app new workplace (device), The latter looks up the resume for details (profile, appearance, skills) and adds it to its local "workplace directory" just like other native apps. Users can now launch the app, or discover it using device-specific search features. And, users and other apps can now target this app for tasks matching its listed capabilities ("url handling"). Isn't that neat?
But wait - there's more. The PWA can also list its resume in app stores just like native apps (e.g., publish to Microsoft Store for Windows devices). When users Install from app store, they just trigger the same interview process. Installability and discoverability for the win!
Creating an Web App Manifest
From a PWA developer perspective, creating a manifest involves:
- Create a manifest.json and populating its properties.
- Linking it to app HTML to advertise your PWA status. Ex:
<link rel="manifest" href="/manifest.json">
Create your manifest with any text editor or IDE - just make sure your JSON is valid. Start with a minimal manifest to get a working PWA. Then iteratively add new members to improve PWA experience. Then add capability-driven attributes related to Web APIs you support.
Audit your PWA with tools like PWABuilder to find, and fix, issues in your manifest so you can deliver a best-in-class PWA experience to users.
What does a minimal manifest need?
The specification defines a number of member attributes - but a suggested minimal manifest should have at least these three - where start_url defines the entry point (default path shown) when app is launched on device.
{
"name": "My Sample PWA",
"lang": "en-US",
"start_url": "/"
}
A user-friendly description of the supported members can be read here - let's see what our sample PWA is declaring for instance:
-
short_name- app name for constrained spaces (e.g., home screen) -
categories- hints for stores or app catalogs. (See W3C examples) -
display- how much of browser UI does user see in app? -
background_color- placeholder to show (before stylesheet loads) -
theme_color- default theme color for app -
scope- what web pages can be viewed (navigation scope) -
description- what is the app about? -
icons- array of icon images used in various contexts -
screenshots- showcase application UI/UX (e.g., for app stores)
What is a good manifest?
A good Manifest provides additional properties that help deliver the optimal experience for the user on that device. This can include:
- adding recommended members and experimental members
- adding properties to unlock new capabilities on device.
For the first part, an actionable step is to use audit tools like PWABuilder that grade manifest quality and help fix issues interactively (see example below). Look for our Week 3: Developer Tools coverage for more details.
For the second part, we talked about two things
| Experimental members |
|---|
| These are manifest members that are being evaluated for future inclusion, but subject to change. Browser platforms may offer early implementations under a flag for evaluation - but keep in mind that these could change, and be unevenly supported across browsers. |
|
Example Our sample PWA declares a "url_handlers" member. This is an experimental feature that allows the app to register itself as a launch target when user wishes to open associated URLs. There is now a proposal to replace this with a "handle_links" member instead. |
| Web capabilities |
|---|
| The manifest can be used to declare support for using new Web APIs that unlock app access to rich platform hardware and features. |
|
Example: The "share_target" (used with the Web Share API), activates PWA ability to share content with other apps like any other native app. Watch for Week 2, when we talk about advanced capabilities. |
A final thought:
Remember our analogy for the manifest being a resume for the PWA? Where manifest "members" reflect different sections related to identity, characteristics and capability?
Think of web capabilities and other open web technologies (e.g, Service Workers) as being a rolodex of team-mates that this app can call upon, to get the work done. They can now list those skills on their resume because it's a skill they are capable of. However, their ability to do that job on a given device is dependent on the availability of those teammates. Think of "feature detection" as equivalent to making a call to see if the required colleague is around before committing to support that task.
Exercise: Inspect Sample PWA Manifest
We covered a lot today - and now it's your turn to learn by actively exploring the concepts. Pick a different Sample App.
- Inspect its Manifest in DevTools. What members did it define?
- Audit it with PWABuilder. What gaps did it identify?
- Explore the Manifest.
- Are any experimental members in use? What do they do?
- Are any capabilities declared? What Web APIs are behind them?
Share your insights using #30DaysOfPWA - we'd love to see them!
Want to read more content from Microsoft technologists? Don't forget to follow Azure right here on dev.to:
