Web App Manifest Setup Checklist

: Essential Guide for PWAs

Want to turn your website into a Progressive Web App (PWA)? You need a web app manifest. Here's what you need to know:

A manifest is a JSON file that defines how your web app works when installed
It sets up your app's name, icons, start URL, and display settings
With a manifest, users can add your web app to their home screen

Key manifest properties:

Property	Purpose
name	Full app name
short_name	Shorter name for icons
icons	Different sized app icons
start_url	Where the app begins
display	How the app looks (fullscreen, etc.)
theme_color	Main color theme

To set up your manifest:

Create a JSON file named manifest.json
Include essential properties (name, icons, start_url)
Place it in your website's root directory

Link it in your HTML:

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

Remember:

Use HTTPS for your web app
Test on different browsers and devices
Keep your manifest up-to-date

By following this checklist, you'll create a solid foundation for your PWA, making it more accessible and user-friendly across devices.

Key Manifest Properties

Your PWA's manifest is its ID card. Here's what you need to include:

App Name

Give your app a clear identity:

{
  "name": "Weather Forecast Pro",
  "short_name": "Weather"
}

name is the full title (max 45 characters). short_name is for app icons (max 12 characters).

App Description

Sum up your app's purpose in under 300 characters:

{
  "description": "Get accurate weather forecasts with real-time updates and severe weather alerts."
}

Start URL

Tell the browser where to begin:

{
  "start_url": "/home.html"
}

Display Mode

Choose how your app looks:

{
  "display": "standalone"
}

Options include fullscreen, standalone, minimal-ui, and browser. Most PWAs use standalone.

App Icons

Provide icons for different devices:

{
  "icons": [
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

Include at least 192x192 and 512x512 pixel icons.

Colors

Set your app's visual theme:

{
  "theme_color": "#4285f4",
  "background_color": "#ffffff"
}

theme_color affects the toolbar, while background_color is for the splash screen.

App Scope

Define your app's content boundaries:

{
  "scope": "/"
}

This allows access to all pages under the root directory.

Making the Manifest File

Let's create a manifest file for your PWA. It's easier than you think.

File Naming

Call it manifest.json. Simple, right?

JSON Format

Your manifest file is just a JSON object. Here's what it looks like:

{
  "name": "Weather Forecast Pro",
  "short_name": "Weather",
  "start_url": "/home.html",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#4285f4",
  "icons": [
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

You NEED name or short_name and start_url. The rest? Nice to have.

File Location

Put manifest.json in your website's root directory. Easy to find, easy to read.

Now, link it in your HTML:

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

Need credentials? Add this:

<link rel="manifest" href="/manifest.json" crossorigin="use-credentials">

That's it. You've got a manifest file. Your PWA is one step closer to reality.

Connecting the Manifest

Let's link your manifest file to your HTML. This is key for browsers to use your web app manifest.

Add the Link Tag

Put this in the <head> of your HTML:

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

Add this to every HTML page in your Progressive Web App.

Need credentials? Use this instead:

<link rel="manifest" href="/manifest.json" crossorigin="use-credentials">

Check It's Working

Here's how to make sure everything's set up right:

1. Use Chrome DevTools

Open your app in Chrome, right-click, and hit "Inspect". Go to "Application" > "Manifest". You'll see your manifest properties.

2. Check the Network Tab

In DevTools, go to "Network" and refresh. Look for a request to your manifest file with a 200 status code.

3. Validate the JSON

Use an online JSON validator to check your manifest file format.

Pro tip: Double-check your manifest file path in the href attribute. A wrong path can cause a 404 error.

Icon Guidelines

Creating icons for your web app? Here's what you need to know:

Icon Sizes

You need two main sizes:

192x192 pixels: For most Android devices
512x512 pixels: For high-res displays and splash screens

Want better compatibility? Add these:

48x48, 72x72, 96x96, 128x128, and 144x144 pixels

Here's how to list them in your manifest:

"icons": [
  { "src": "icon-48.png", "sizes": "48x48", "type": "image/png" },
  { "src": "icon-72.png", "sizes": "72x72", "type": "image/png" },
  { "src": "icon-96.png", "sizes": "96x96", "type": "image/png" },
  { "src": "icon-128.png", "sizes": "128x128", "type": "image/png" },
  { "src": "icon-144.png", "sizes": "144x144", "type": "image/png" },
  { "src": "icon-192.png", "sizes": "192x192", "type": "image/png" },
  { "src": "icon-512.png", "sizes": "512x512", "type": "image/png" }
]

Image Types

PNG is common, but you've got options:

PNG: Great for transparent icons
WebP: Better compression (Chrome supports it)
JPEG: For photo-like icons without transparency
SVG: Scalable icons that look good at any size

Use the right MIME type in your manifest:

{ "src": "icon.png", "sizes": "192x192", "type": "image/png" }
{ "src": "icon.webp", "sizes": "192x192", "type": "image/webp" }
{ "src": "icon.svg", "sizes": "any", "type": "image/svg+xml" }

Icon Purpose

Tell browsers how to use your icon with the purpose attribute:

any: Default. Use anywhere.
maskable: Can have a mask or shape applied.
monochrome: Single-color design, can be recolored.

In your manifest:

{
  "src": "icon-maskable.png",
  "sizes": "192x192",
  "type": "image/png",
  "purpose": "maskable"
}

You can combine purposes:

{
  "src": "icon-versatile.png",
  "sizes": "512x512",
  "type": "image/png",
  "purpose": "any maskable"
}

Extra Manifest Options

Want to make your web app pop? Let's dive into some cool manifest options.

Language Settings

Set your app's language and text direction:

{
  "lang": "fr-CA",
  "dir": "ltr"
}

This sets French (Canadian) as the language and left-to-right text direction.

Screen Orientation

Control how your app looks on devices:

{
  "orientation": "portrait-primary"
}

You can choose portrait, landscape, or specific modes like portrait-primary.

App Categories

Group your app to help users find it:

{
  "categories": ["productivity", "utilities"]
}

Pick from standard categories like "business", "education", or "games".

App Screenshots

Show off your app:

{
  "screenshots": [
    {
      "src": "screenshot1.jpg",
      "sizes": "1280x720",
      "type": "image/jpeg"
    },
    {
      "src": "screenshot2.jpg",
      "sizes": "1280x720",
      "type": "image/jpeg"
    }
  ]
}

Remember:

Use images at least 320x320 pixels
Max size: 3840x3840 pixels
Longest side can't be more than 2.3 times the shortest

App Shortcuts

Give users quick access:

{
  "shortcuts": [
    {
      "name": "New Message",
      "url": "/compose",
      "icons": [{ "src": "compose-icon.png", "sizes": "96x96" }]
    },
    {
      "name": "Inbox",
      "url": "/inbox"
    }
  ]
}

Each shortcut needs a name and url. Icons are optional but nice to have.

Checking Your Manifest

After setting up your web app manifest, you need to make sure it's correct. Here's how:

Browser Tools

Chrome DevTools has a Manifest pane in the Application panel. It shows your manifest's properties in a readable format and helps check if images are loading right.

To use it:

Open Chrome DevTools
Go to Application panel
Click on Manifest pane

This lets you spot issues quickly.

Online Checkers

For a deeper check, try online tools. The Web App Manifest Validator by redirection.io is good. It checks over 60 things on each page, including:

Website quality
Performance
SEO
Content issues

These tools catch errors you might miss.

Common Mistakes

Watch out for these:

Mistake	Problem	Solution
JSON typos	Manifest breaks	Check all names and values
Missing key properties	Incomplete manifest	Include `name`, `short_name`, `start_url`, and `icons`
Wrong file type	Browser can't read it	Use `Content-Type: application/manifest+json` or `application/json`
Bad icon sizes	Icons might not show	Use 192px and 512px icons
Wrong `display` value	App might not launch right	Use `standalone`, `fullscreen`, or `minimal-ui`

"The web manifest is simple JSON, but it's easy to make mistakes", says a Chrome team dev expert.

To avoid these:

Use a JSON validator
Test on different devices and browsers
Clear browser data before testing

Publishing Your Manifest

Ready to make your web app manifest live? Here's what you need to know:

HTTPS Is a Must

Your web app MUST use HTTPS. It's not optional. Why?

Secure connections
User data protection
Service worker functionality

"Is served over HTTPS — I hope you can handle that." - Subodh Garg, Author

No HTTPS yet? Try Certbot to help you switch.

Testing vs. Live

Your manifest might need tweaks:

Environment	What to Do
Testing	Use relative URLs, include debug info
Live	Use absolute URLs, remove debug info

Don't forget to update the start_url when going live.

Publishing Steps

Confirm HTTPS
Add manifest file to your site
Link it in your HTML:

<link rel="manifest" href="manifest.webmanifest">

Test on various devices and browsers

"More than 50 percent of all smartphone users move mobile apps to the home screen for easy access." - ComScore

Make sure everything works smoothly before you hit that publish button.

Browser Support

Your web app manifest needs to work on different browsers. Here's how to check and what to do if it doesn't.

Checking Browsers

Test your manifest on these browsers:

Browser	PWA Support
Chrome	Full support
Safari	Limited support
MS Edge	Good support, needs specific testing
Firefox	Full support in new versions

Use browser dev tools to check for manifest errors.

Backup Plans

Not all browsers fully support manifests. Here's what to do:

1. Fallback content

Make sure your web app works without manifest features.

2. Feature detection

Check if features are supported:

if ('serviceWorker' in navigator) {
  // Use service worker
}

3. PWACompat

This library helps with non-compliant browsers:

<script async src="https://cdn.jsdelivr.net/npm/pwacompat" crossorigin="anonymous"></script>

4. iOS issues

PWAs on iOS don't have auto-install prompts. Show users how to add your app manually.

"PWAs need web browser compatibility. It's key to stop websites from constantly reloading."

Keeping Manifests Up-to-Date

Keeping your web app manifest current is key for your PWA's success. Here's how to do it:

Update Tips

1. Test regularly

Check your PWA on different browsers and devices. It's the best way to spot issues early.

2. Use feature detection

Don't assume all browsers support every feature. Use JavaScript to check:

if ('serviceWorker' in navigator) {
  // Service worker code here
}

3. Know what triggers updates

Chrome checks for manifest changes when your PWA starts. Here's what matters:

Property	Windows/macOS	Android
name	✓	✗
display	✓	✓
scope	✓	✓
start_url	✓	✓
icons	✗	✗

4. Force updates when needed

Add a version query to your manifest link:

<link rel="manifest" href="/manifest.json?v=2" />

5. Remember iOS limitations

iOS doesn't update manifests after install. Users need to reinstall for changes to take effect.

Version Control

Track your manifest changes with Git. It's not just for code:

Use clear commit messages:

Update manifest.json: Change theme_color to #00FF00

Test changes in feature branches before merging.
Set up automated testing in your CI/CD pipeline.
Keep a changelog for your team.

Wrap-Up

Let's recap the key points for setting up a web app manifest:

The manifest is a JSON file with crucial metadata about your web app. It needs these essential properties:

name or short_name
icons (192px and 512px sizes)
start_url
display or display_override

Put your manifest.json file at your web app's root and link it in your HTML:

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

Serve your PWA over HTTPS (except for localhost during development). While browser support varies, Chromium browsers offer the most consistent PWA installation across desktop OSs.

Use browser developer tools to check your manifest. Chrome DevTools' Application panel is particularly useful.

Keep in mind that some manifest changes might not take effect right away on all platforms.

FAQs

How do I create a web manifest file?

Creating a web manifest file is simple:

Name it manifest.json (or manifest.webmanifest)
Put it in your website's root directory
Use this JSON format:

{
  "name": "My Web App",
  "short_name": "MyApp",
  "start_url": "/",
  "display": "standalone",
  "icons": [
    {
      "src": "/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

How to make a web manifest?

Making a web manifest is easy:

Create a JSON file with your app details
Include key info like name, icons, and start URL
Save it as manifest.json in your site's root folder
Link it in your HTML:

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

What is manifest Webmanifest for?

The web manifest is the secret sauce for Progressive Web Apps (PWAs). It tells browsers:

Your app's name and description
What icons to use
Where to start
How to display it

With this info, your PWA can strut its stuff on supported devices, looking and feeling more like a native app.