Web App Manifest Issues
What This Means
The web app manifest is a JSON file that tells browsers how your PWA should behave when installed. Manifest issues prevent:
- "Add to Home Screen" prompts from appearing
- Correct app name and icons on device
- Proper standalone app experience
- App appearance in system app switchers
How to Diagnose
1. Chrome DevTools
- Open DevTools (F12)
- Go to Application tab
- Click Manifest in sidebar
- Review errors and warnings
2. Lighthouse PWA Audit
- DevTools > Lighthouse
- Check "Progressive Web App"
- Run audit
- Review "Installable" section
3. Common Error Messages
| Error | Meaning |
|---|---|
| "No manifest detected" | Missing <link rel="manifest"> |
| "Manifest start_url is not valid" | start_url doesn't load |
| "No matching service worker" | SW not registered for manifest scope |
| "Icons required" | Missing or invalid icon specifications |
4. Console Check
// Verify manifest is linked
document.querySelector('link[rel="manifest"]')?.href;
// Check for install prompt support
window.addEventListener('beforeinstallprompt', (e) => {
console.log('Install prompt available');
});
General Fixes
Complete Manifest Example
{
"name": "BlueFrog Analytics Dashboard",
"short_name": "BlueFrog",
"description": "Website analytics and optimization platform",
"start_url": "/?source=pwa",
"scope": "/",
"display": "standalone",
"orientation": "portrait",
"background_color": "#ffffff",
"theme_color": "#1f75fe",
"categories": ["business", "productivity"],
"icons": [
{
"src": "/icons/icon-72.png",
"sizes": "72x72",
"type": "image/png"
},
{
"src": "/icons/icon-96.png",
"sizes": "96x96",
"type": "image/png"
},
{
"src": "/icons/icon-128.png",
"sizes": "128x128",
"type": "image/png"
},
{
"src": "/icons/icon-144.png",
"sizes": "144x144",
"type": "image/png"
},
{
"src": "/icons/icon-152.png",
"sizes": "152x152",
"type": "image/png"
},
{
"src": "/icons/icon-192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/icon-384.png",
"sizes": "384x384",
"type": "image/png"
},
{
"src": "/icons/icon-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/maskable-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
],
"screenshots": [
{
"src": "/screenshots/desktop.png",
"sizes": "1280x720",
"type": "image/png",
"form_factor": "wide"
},
{
"src": "/screenshots/mobile.png",
"sizes": "750x1334",
"type": "image/png",
"form_factor": "narrow"
}
],
"shortcuts": [
{
"name": "View Dashboard",
"url": "/dashboard",
"icons": [{ "src": "/icons/dashboard-96.png", "sizes": "96x96" }]
},
{
"name": "Run Audit",
"url": "/audit/new",
"icons": [{ "src": "/icons/audit-96.png", "sizes": "96x96" }]
}
]
}
Required Fields for Installability
{
"name": "App Name",
"short_name": "App",
"start_url": "/",
"display": "standalone",
"icons": [
{ "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" },
{ "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }
]
}
Link Manifest in HTML
<head>
<!-- Web App Manifest -->
<link rel="manifest" href="/manifest.json">
<!-- Theme color for browser UI -->
<meta name="theme-color" content="#1f75fe">
<!-- iOS Safari support -->
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="default">
<meta name="apple-mobile-web-app-title" content="BlueFrog">
<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png">
<!-- Windows tiles -->
<meta name="msapplication-TileColor" content="#1f75fe">
<meta name="msapplication-TileImage" content="/icons/mstile-144.png">
</head>
Display Modes
// Options for "display" field:
{
"display": "standalone" // App-like (recommended)
// OR
"display": "fullscreen" // No browser UI at all
// OR
"display": "minimal-ui" // Minimal browser controls
// OR
"display": "browser" // Normal browser tab
}
Maskable Icons
For Android adaptive icons, provide maskable versions:
{
"icons": [
{
"src": "/icons/icon-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "any"
},
{
"src": "/icons/maskable-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
]
}
Maskable icon requirements:
- Important content in center safe zone (80% circle)
- Background color fills the entire icon
- Use Maskable.app to test
Fix Common Issues
Missing manifest link:
<link rel="manifest" href="/manifest.json" crossorigin="use-credentials">
Invalid start_url:
{
"start_url": ".", // Relative to manifest location
// OR
"start_url": "/", // Site root
// OR
"start_url": "/?utm_source=pwa" // Track PWA launches
}
CORS issues:
// Ensure manifest is served with correct headers
// Content-Type: application/manifest+json
# Nginx configuration
location /manifest.json {
add_header Content-Type application/manifest+json;
add_header Access-Control-Allow-Origin *;
}
Platform-Specific Guides
| Platform | Guide |
|---|---|
| Next.js | Next.js PWA |
| WordPress | WordPress PWA |
| Shopify | Shopify PWA |
Verification
- Chrome DevTools > Application > Manifest (no errors)
- Lighthouse PWA audit passes "Installable" checks
- Install prompt appears on supported browsers
- Installed app displays correct name and icon
Common Mistakes
| Mistake | Fix |
|---|---|
| JSON syntax errors | Validate with JSONLint |
| Missing 512x512 icon | Add required large icon |
| Wrong MIME type | Serve as application/manifest+json |
| start_url outside scope | Ensure start_url within defined scope |
| Relative URLs for icons | Use absolute paths from site root |