A manifest.json file is essential for creating Progressive Web Apps (PWAs) that provide native app-like experiences. This comprehensive guide shows you exactly how to create, configure, and implement a manifest.json file that meets 2025 web standards and enhances user engagement across all devices.
What is a Manifest.json File
A manifest.json file is a JSON document that contains metadata about your web application. This file tells browsers how your app should behave when installed on a user’s device, including its name, icons, colors, and display preferences. The web app manifest is a crucial component for creating Progressive Web Apps that can be installed directly from the browser.
Modern browsers use the manifest file to enable features like add-to-home-screen prompts, splash screens, and full-screen display modes. According to 2024 data from Chrome Platform Status, over 87% of PWAs in the United States now include properly configured manifest files, making it a standard requirement for modern web development.
Essential Manifest.json Properties
Your manifest.json file requires specific properties to function correctly. The most critical elements include name, short_name, start_url, display mode, theme_color, and background_color. These manifest properties define how your app appears and behaves when users interact with it outside of a traditional browser window.
The icons array is particularly important, requiring multiple sizes to support different devices and contexts. Google recommends including icons at 192×192 and 512×512 pixels minimum, with additional sizes for optimal display across Android, iOS, and desktop environments in 2025.
Required Manifest Properties
The required manifest properties include name (or short_name), icons array, start_url, and display mode. Without these essential elements, browsers cannot properly install or display your PWA. The name property should be descriptive and match your app’s branding, while short_name provides a concise version for limited display spaces like home screen labels.
Optional But Recommended Properties
Optional manifest properties enhance user experience significantly. Theme_color defines the browser UI color, background_color sets the splash screen background, and orientation controls screen rotation. The scope property limits which pages belong to your PWA, while categories help app stores classify your application appropriately for better discoverability.
Step-by-Step Manifest.json Creation Process
Creating a manifest.json file begins with opening your preferred text editor and creating a new JSON file in your website’s root directory. Start with basic structure using curly braces and add properties one by one, ensuring proper JSON syntax with quoted keys and appropriate data types for each value.
Begin with the basic manifest structure including name, short_name, and start_url properties. Then add your icons array with properly formatted objects containing src, sizes, and type properties. Finally, configure display preferences, colors, and any additional properties relevant to your specific application needs.
Creating the Basic Structure
Start your manifest file creation with opening and closing curly braces, then add the name property with your full application name in quotes. Follow with short_name for abbreviated display, start_url pointing to your app’s main page, and display set to standalone for app-like experience. Ensure each property except the last includes a trailing comma for valid JSON syntax.
Adding Icons and Visual Elements
The icons array requires careful attention to detail with each icon object containing src, sizes, and type properties. Create multiple icon sizes starting with 192×192 and 512×512 pixels, saved as PNG files for best compatibility. Add theme_color and background_color properties using hex color codes that match your brand identity and provide visual consistency across different platforms.
Complete Manifest.json Code Example
Here’s a comprehensive manifest.json example that includes all essential properties for a modern PWA. This example demonstrates proper JSON formatting, required properties, and optional enhancements that improve user experience across desktop and mobile devices in 2025.
Copy this manifest code and customize the values to match your application’s requirements. Replace placeholder text with your actual app name, adjust colors to match your branding, and ensure all file paths point to existing resources on your server for proper functionality.
How to Link Manifest.json to Your Website
After creating your manifest.json file, you must link it to your HTML pages using a link tag in the head section. Add the following code to every page where you want PWA functionality: <link rel=”manifest” href=”/manifest.json”>. This manifest link tells browsers where to find your app’s configuration information.
Place the manifest link tag in the head section of your HTML document, preferably near other meta tags for organization. Ensure the href attribute points to the correct file path relative to your domain root, and verify the file is accessible by testing the URL directly in your browser before deploying to production.
HTML Implementation Code
Insert the manifest link HTML between your opening and closing head tags using the exact syntax: <link rel=”manifest” href=”/manifest.json”>. This link element must appear on every page where you want PWA installation prompts to appear, ensuring consistent behavior across your website’s entire user journey.
Verifying Manifest Connection
Test your manifest connection by opening Chrome DevTools, navigating to the Application tab, and checking the Manifest section. A properly linked manifest file will display all your properties with preview icons and colors. Any errors or missing properties will appear here, allowing you to troubleshoot issues before users encounter them.
Manifest.json Best Practices for 2025
Modern manifest best practices emphasize accessibility, performance, and cross-platform compatibility. Use descriptive names that clearly identify your application, include comprehensive icon sets covering all device resolutions, and test thoroughly across different browsers and operating systems to ensure consistent behavior.
Follow the latest PWA standards by including proper MIME types for all resources, using HTTPS for secure connections, and implementing service workers alongside your manifest for complete offline functionality. Google’s 2024 PWA guidelines recommend testing with Lighthouse audits to achieve optimal performance scores and user engagement metrics.
Common Manifest.json Errors and Solutions
The most frequent manifest errors include invalid JSON syntax, missing required properties, and incorrect file paths for icons. Syntax errors often result from missing commas, unquoted keys, or trailing commas after the last property. Use JSON validators to check your file structure before deployment and avoid these common mistakes.
Icon-related manifest problems frequently occur when image files don’t exist at specified paths or when sizes don’t match declared dimensions. Ensure all referenced images are accessible via HTTP requests and match their declared sizes exactly. Browser console errors will indicate specific issues with icon loading or property validation.
Debugging JSON Syntax Issues
Use online JSON validators to identify syntax errors in your manifest file before testing in browsers. Common issues include missing quotes around property names, incorrect comma placement, and mismatched brackets. Browser developer tools also provide detailed error messages indicating specific line numbers and problem descriptions for efficient troubleshooting.
Fixing Icon and Path Problems
Resolve icon path errors by verifying file existence using direct URL access in your browser. Ensure image dimensions match declared sizes exactly, use supported file formats (PNG, JPG, SVG), and provide appropriate MIME types. Create a systematic icon testing checklist covering all declared sizes and verify loading across different devices and screen densities.
Testing Your Manifest.json File
Comprehensive manifest testing involves multiple tools and browsers to ensure cross-platform compatibility. Use Chrome DevTools Application tab for initial validation, then test installation prompts on actual mobile devices. The Manifest section shows property values, icon previews, and any validation warnings that need attention.
Run Lighthouse audits to evaluate your PWA’s overall quality including manifest implementation. These audits provide specific recommendations for improvement and score your app against current web standards. Test installation behavior on Android, iOS, and desktop platforms to verify consistent user experiences across all target devices.
Related video about how to create a manifest.json file
This video complements the article information with a practical visual demonstration.
Most asked questions about how to create a manifest.json file
What is the purpose of a manifest.json file?
A manifest.json file provides metadata that tells browsers how your web application should behave when installed on a user’s device. It enables Progressive Web App features like add-to-home-screen prompts, custom splash screens, and app-like display modes. The file contains essential information including app name, icons, colors, and display preferences that create native app experiences within web browsers.
Where should I place my manifest.json file?
Place your manifest.json file in your website’s root directory alongside other important files like robots.txt and sitemap.xml. This location ensures easy access for browsers and consistent linking across all pages. Link to the manifest using <link rel=”manifest” href=”/manifest.json”> in your HTML head section on every page where you want PWA functionality.
What icon sizes are required for manifest.json?
Include at minimum 192×192 and 512×512 pixel PNG icons in your manifest.json file. For optimal compatibility across all devices and contexts, also include 72×72, 96×96, 128×128, 144×144, 152×152, 384×384, and 1024×1024 pixel versions. Each icon should be properly optimized and include accurate size declarations in the icons array for correct display across different platforms.
Can I use manifest.json without a service worker?
Yes, you can use manifest.json without a service worker, but you’ll miss key PWA benefits like offline functionality and background sync. The manifest enables basic installation features and app-like display, while service workers provide advanced capabilities. For complete PWA functionality that meets modern web standards, implement both manifest.json and service workers together for optimal user experience.
How do I test if my manifest.json is working correctly?
Test your manifest.json using Chrome DevTools by opening the Application tab and checking the Manifest section. This shows all properties, icon previews, and validation errors. Run Lighthouse audits for comprehensive PWA scoring, test installation prompts on mobile devices, and verify cross-browser compatibility. Use online JSON validators to check syntax before deployment to production environments.
What display modes are available in manifest.json?
Available display modes include standalone (app-like without browser UI), fullscreen (complete screen usage), minimal-ui (minimal browser controls), and browser (standard web page display). Standalone is most popular for PWAs as it provides native app experience. Choose based on your app’s functionality requirements and user interaction patterns for optimal engagement and usability.
| Key Aspect | Important Details | Benefit |
|---|---|---|
| File Location | Root directory with proper HTML linking | Easy browser access and PWA functionality |
| Required Properties | Name, icons, start_url, display mode | Basic PWA installation and app behavior |
| Icon Requirements | 192×192 and 512×512 minimum PNG formats | Cross-platform compatibility and visual consistency |
| Testing Tools | Chrome DevTools, Lighthouse audits, validators | Error detection and performance optimization |
| Best Practices | Valid JSON syntax, comprehensive icons, HTTPS | Professional PWA meeting 2025 web standards |