How to Build and Configure a Progressive Web App with Web App Manifest

A Progressive Web App (PWA) is a technology that brings native app-like experiences to websites. Users can install your website on their home screen and use it offline, all without an app store. This guide covers how to build a PWA using Web App Manifest, a JSON file that tells browsers essential information about your web app.

What is a Progressive Web App and Why It Matters

A Progressive Web App combines web technologies like Service Workers and Web App Manifest to deliver native app-like experiences. PWAs can be installed on home screens, work offline, load instantly, and send push notifications—all without app store distribution. They're especially valuable for reaching users on budget devices and in areas with unreliable internet.

• Install directly to the home screen like a native app
• Function offline with cached content
• Load instantly even on slow networks
• Send push notifications to users
• No app store approval or download friction required

Understanding the Web App Manifest File

The Web App Manifest is a JSON file containing metadata about your web app—name, description, icons, theme colors, and display mode. Browsers read this file to install your PWA correctly. Place manifest.json in your site root and link it in every HTML page's with . This single file tells the browser everything needed to display your app properly when installed.

• A JSON file describing your web app's identity
• Located in the website root directory
• Referenced in HTML with rel="manifest"
• Contains essential properties like name, icons, and colors

Required and Recommended Manifest Fields

Essential fields include: name (full app name), short_name (≤12 characters for icon labels), icons (array with sizes and MIME types), start_url (entry page), display ("standalone" for full screen or "browser" for tab), background_color (splash screen color), and theme_color (system UI color). The short_name must be concise because it displays beneath your icon on the home screen. Modern browsers handle most fields, but older ones may require additional properties.

• name: Full app name for install prompt
• short_name: Abbreviated name for home screen
• icons: Array with multiple sizes (192px, 512px, etc.)
• start_url: Page to load when user opens the app
• display: "standalone", "browser", or "fullscreen"
• theme_color and background_color: Colors for OS and splash screen

App Icons: Sizes and Formats Needed

Your PWA needs multiple icon sizes to display correctly across devices. Minimum sizes: 192×192 px (home screen) and 512×512 px (installation splash screen). Additional sizes like 144×144 or 256×256 px help on specific devices. Use PNG or WebP with a transparent background so the operating system can apply its own background color. Include each icon in the manifest's icons array with both sizes and purpose properties (e.g., "any" for general use or "maskable" for adaptive icons on Android).

• 192×192 px: Standard size for home screen icons
• 512×512 px: Large icon for installation splash and galleries
• 144×144 and 256×256 px: Additional fallback sizes
• PNG or WebP format with transparency recommended
• Maskable icon support for adaptive icons on Android

Service Workers Explained (Offline Caching Basics)

A Service Worker is a JavaScript file running in the background, even when your web page is closed. Its primary role is to cache resources (HTML, CSS, images, JavaScript) so your PWA works offline. Service Workers also handle push notifications and background sync. You don't need a complex Service Worker—caching your home page and critical static assets is a solid start. Register it in your HTML with a simple JavaScript snippet that calls navigator.serviceWorker.register(). The browser manages its lifecycle automatically.

• JavaScript file running in background independent of the web page
• Intercepts network requests to serve cached resources
• Enables offline functionality and faster load times
• Handles push notifications and background data sync
• Registered once per PWA through a client-side script

Installability Criteria: Making "Add to Home Screen" Appear

Browsers show an install prompt when your PWA meets specific criteria: valid manifest.json with required fields, HTTPS on all pages, registered Service Worker, icon at least 192×192 px, and sufficient user engagement (typically 30+ seconds on-site). Chrome, Edge, and Samsung Internet fully support PWA installation prompts. iOS Safari has limitations but allows home screen shortcuts. When all criteria are met, many browsers automatically show the install prompt, though you can trigger a custom prompt using the beforeinstallprompt event.

• Valid manifest.json with name, icons, and other required fields
• HTTPS enforced site-wide (HTTP won't work)
• Service Worker registered and handling fetch requests
• Icons at 192×192 px and 512×512 px minimum
• User engagement signal (time spent or interactions on site)

Testing Your PWA with Lighthouse

Google Lighthouse is a free audit tool built into Chrome DevTools that validates PWA compliance. Open DevTools, go to the Lighthouse tab, select "PWA," and click "Analyze page load." Lighthouse scores your app across Performance, Accessibility, Best Practices, SEO, and PWA compliance. The report flags missing icons, unregistered Service Workers, invalid manifests, and other issues. Run audits regularly during development to catch problems early. Fixing issues identified by Lighthouse typically results in better overall web performance and user experience.

• Open Chrome DevTools and navigate to the Lighthouse tab
• Select PWA and click "Analyze page load"
• Review detailed report highlighting missing or incorrect fields
• Check manifest validity, icon sizes, and Service Worker registration
• Retest after fixes to verify improvements

PWA vs. Native App: Pros, Cons, and When to Use Each

PWAs and native apps each have strengths. PWAs offer instant access without app store distribution, automatic updates, and lower storage requirements. Native apps provide deeper OS integration like GPS, microphone, and hardware sensors. PWAs suit content-driven apps (news, blogs, productivity tools), while native apps excel for graphics-intensive games and apps requiring direct hardware access. Many companies launch PWAs first to reach users broadly, then develop native apps if specialized features demand it.

• PWA benefits: No app store, instant updates, minimal storage
• PWA: Works well on budget and older devices
• Native app benefits: Direct access to GPS, microphone, sensors
• Native app: Superior performance for graphics-heavy games
• Strategy: Start with PWA, build native app only if specialized features required

Common Manifest and PWA Setup Mistakes

Frequent issues include: missing in HTML, incorrect icon sizes or formats, JSON syntax errors in manifest.json, Service Worker registration failures, and non-HTTPS sites (PWAs require encryption). Another mistake is forgetting to set start_url, which can cause the app to open to the wrong page. Mismatched colors between background_color and icons can make the splash screen look broken. Debugging tip: Open Chrome DevTools, go to the Application tab, select your site, and inspect the Manifest section to spot problems immediately.

• Missing tag in HTML
• Incorrect icon sizes (use 192×192 and 512×512 minimum)
• JSON syntax errors in manifest.json file
• Service Worker fails to register or has script errors
• Site not using HTTPS (mandatory for PWAs)
• Forgetting to specify start_url pointing to correct home page